Resources

Troubleshooting

Common problems, their causes, and how to fix them. Start with conductor doctor — it catches most issues automatically.

Diagnostic commands

start here

# Full system health check
conductor doctor

# Verbose server startup (see every event)
conductor mcp start --log-level debug

# Check what plugins are loaded
conductor plugins list

# Validate config file
conductor config validate

# Check config path
conductor config path

Enable debug logging

Debug mode logs every tool call, validation step, and circuit breaker decision to stderr. Start here when something isn't working and you don't know why.

debug mode

# Start in debug mode — every tool call logged to stderr
CONDUCTOR_LOG_LEVEL=debug conductor mcp start

# Sample debug output:
# [debug] Plugin loaded: filesystem (7 tools)
# [debug] Plugin loaded: shell (4 tools)
# [debug] Plugin loaded: git (9 tools)
# [info]  Conductor ready (22 tools across 6 plugins)
# [debug] Tool call: filesystem.read {"path":"./package.json"}
# [debug] Validation passed
# [debug] No approval required
# [debug] Circuit CLOSED — proceeding
# [debug] Handler complete in 2ms
# [debug] Audit entry written

Common issues

Tools don't appear in my AI client

Client not restarted after config changeConfig JSON syntax errorWrong config file locationConductor not installed globally

# 1. Verify Conductor is installed
which conductor || npx @useconductor/conductor --version

# 2. Validate your config file
conductor config validate

# 3. Test the connection manually
conductor mcp start --log-level debug

# 4. Hard restart your AI client (quit + reopen, not just reload)

"command not found: conductor"

Global npm install failedPATH doesn't include npm global bin

# Check npm global bin location
npm bin -g

# Add it to your PATH (zsh example)
echo 'export PATH="$(npm bin -g):$PATH"' >> ~/.zshrc
source ~/.zshrc

# Or skip the global install entirely — use npx in your AI client config:
# "command": "npx", "args": ["-y", "@useconductor/conductor"]

Shell commands rejected / not in allowlist

Shell plugin allowlist is empty by defaultCommand not in allowedCommands

# Interactive setup
conductor config setup shell

# Or manually edit ~/.conductor/config.json:
# {
#   "plugins": {
#     "shell": {
#       "allowedCommands": ["ls", "cat", "git", "npm", "node", "python3"]
#     }
#   }
# }

Filesystem operations refused

Path outside allowedPathsallowedPaths not configured

# Add paths to the allowlist
# ~/.conductor/config.json
# {
#   "plugins": {
#     "filesystem": {
#       "allowedPaths": ["~", "/tmp", "/var/www"]
#     }
#   }
# }

# Check what paths are currently allowed
conductor plugins info filesystem

Database connection fails

Wrong connection stringDatabase not runningMissing credentialsFirewall blocking connection

# Test the connection string directly
conductor db test --connection "postgresql://user:pass@localhost:5432/mydb"

# Check plugin config
conductor plugins info database

# View detailed error
conductor mcp start --log-level debug

Circuit breaker keeps tripping

Underlying service is downThreshold too low for the toolTimeout too short for slow operations

# Check circuit states
conductor circuit list

# Reset a specific circuit
conductor circuit reset tool.name

# Increase threshold for a flaky tool in config:
# "circuitBreaker": {
#   "overrides": {
#     "web.fetch": { "failureThreshold": 10, "timeout": 15000 }
#   }
# }

Audit log chain verification fails

Log file was manually editedDisk corruptionLog was truncated by a log rotation tool

# Check which entry broke the chain
conductor audit verify --verbose

# Archive the broken log and start fresh
mv ~/.conductor/audit.log ~/.conductor/audit.log.broken
# A new audit.log will be created on next tool call

# Note: The broken log still contains readable entries
# (the chain verification failure doesn't erase data)

High memory or CPU usage

Debug logging writing large volumesMany plugins with polling (webhooks, watchers)Large audit log file

# Switch to warn level in production
CONDUCTOR_LOG_LEVEL=warn conductor mcp start

# Rotate the audit log
conductor audit export --output audit-backup.json
conductor audit rotate

# Check which plugins are active
conductor plugins list --verbose

Plugin fails to load

Syntax error in plugin fileMissing required config fieldsPlugin requires a package that isn't installedconfigSchema validation failed

# See the exact error
conductor mcp start --log-level debug 2>&1 | grep -A5 "plugin"

# Validate plugin manually
conductor plugins validate my-plugin

# Check config schema issues
conductor config validate

Webhook events not firing

Using stdio transport (webhooks require HTTP)Wrong secret for HMAC verificationFirewall blocking inbound requests

# Webhooks require HTTP transport
conductor mcp start --transport http --port 3000

# Test the webhook endpoint
curl -X POST http://localhost:3000/webhooks \
  -H "Content-Type: application/json" \
  -d '{"type":"test","data":{}}'

# Check webhook config
conductor webhooks list

Still stuck?

Check the FAQ

Covers the most common setup questions.

Open a GitHub issue

Include the output of `conductor doctor` and `conductor mcp start --log-level debug`.