Skip to content

Troubleshooting

Jump to bottom
rluisr edited this page Jul 23, 2026 · 1 revision

Troubleshooting

English | 日本語

Symptom → likely cause → fix. Start with the matching section; when in doubt, check process logs and the run detail event stream.

Startup fails immediately

Message / symptom Fix
ANTHROPIC_API_KEY is required Export a valid key
GITHUB_APP_ID is required Set numeric App ID
GITHUB_APP_PRIVATE_KEY or ..._PATH is required Provide PEM inline or path; path must be readable by the process user
Config Zod / strict parse error Remove unknown keys from maestro.config.*; check types of numbers
Port already in use Change PORT / free the port
Bun version mismatch mise install or use Bun from mise.toml (1.3.14)

GitHub auth / preflight

Symptom Fix
Invalid or expired GitHub credential Re-check App ID + PEM; reinstall App on the org/account
Repository not found / not accessible Confirm owner/repo, App installation includes that repo
Missing permissions: contents, issues, pull_requests App settings → Repository permissions → Read and write for all three + Metadata read → re-install so the new permissions apply
Parent issue is closed Reopen the issue or pick an open one
Works on one repo, 404 on another Installation is repo-subset; add the missing repo to the App install

Required permission set (minimum):

  • Metadata: read
  • Contents: write
  • Issues: write
  • Pull requests: write

Anthropic / Managed Agents

Symptom Fix
Anthropic authentication invalid Rotate/fix ANTHROPIC_API_KEY; confirm org access to Managed Agents
Agent create/update errors Check API key scopes; inspect logs around registry
Session stuck in requires_action Use WebUI resume with instructions, or wait for stale-run-reaper; inspect Claude Console session link from the run
Run exceeds time limits Raise maxRunMinutes / MAX_RUN_MINUTES; split the parent issue
Model rejected Use a supported id (claude-fable-5, claude-opus-4-8, claude-sonnet-5)

Console deep-link workspace: set CONSOLE_WORKSPACE if sessions are not under default.

Runs queue but never start / stay running

  1. Only one process should own the SQLite DB (single-writer)
  2. Check .maestro/run.lock / .maestro/run.lock.lock — stale lock after a crash may need careful removal only if no process is alive
  3. Open run detail → events: last phase and error payload
  4. POST /api/runs/:runId/stop from API or Stop in UI
  5. Confirm stale-run-reaper is not disabled (STALE_RUN_REAPER_ENABLED)

Poller does not pick up issues

Check Expected
WebUI Repositories Target repo listed and enabled
Label Exact match for GITHUB_TRIGGER_LABEL (default agent-run)
Comment trigger Starts with @<GITHUB_BOT_MENTION> run
Issue state Open
App access Installation can read issues on that repo
Interval Wait at least one GITHUB_TRIGGER_POLL_INTERVAL_SECONDS

Old env GITHUB_TRIGGER_REPOS is not used — repos are DB-only.

MCP: GitHub tools fail

Symptom Fix
MCP initialize / tool errors on github Confirm builtin row enabled; App can access repo; installation token mint works (App PEM OK)
Wrong repo data / 403 after multi-repo Avoid shared VAULT_ID; let maestro use managed per-run vaults
Agent does not call GitHub MCP Prompt / permission policy; check tool events in run stream

MCP: custom / Figma / gateway

Symptom Fix
401 from gateway MCP_GATEWAY_TOKEN in env must match vault credential and client Bearer; keep token stable across restarts
initialize failed / HTTP 405 stdio child died or wrong path; check mcp-proxy logs; URL must end with /servers/<name>/mcp
Managed Agents cannot reach URL Must be public HTTPS (or dev tunnel). 127.0.0.1 in DB will never work from Anthropic cloud
CIDR denied Allow Anthropic egress (160.79.104.0/21 or current docs); or only for local tunnel use MCP_GATEWAY_DISABLE_CLIENT_IP_CHECK / dev-tunnel path
dev-tunnel: failed to spawn mcp-proxy pip install mcp-proxy and ensure it is on PATH
timed out waiting for ...:8096 Port busy (lsof -iTCP:8096) or proxy crash-loop
ENABLE_DEV_TUNNEL=true requires NGROK_AUTHTOKEN Set token from ngrok dashboard
ERR_NGROK_4018 Free plan tunnel limit — close other tunnels
UNABLE_TO_GET_ISSUER_CERT_LOCALLY in mcp-proxy Often interactive shell helper CA: set DEV_TUNNEL_DROP_NODE_EXTRA_CA_CERTS=true, or set corporate NODE_EXTRA_CA_CERTS correctly — see docs/DEVELOPMENT.md
Linear origin rejected Enable MCP server URL https://mcp.linear.app/mcp with valid token_env_name

Self-hosted environment

Symptom Fix
Sessions never picked up Worker/poller running with matching ANTHROPIC_ENVIRONMENT_ID + ANTHROPIC_ENVIRONMENT_KEY
Bootstrap / clone failure Worker image has git, bash, curl, jq, openssl, timeout; App PEM mounted; installation has contents:write on repo
Path / mount confusion Expect /workspace/maestro-runs/<64-hex>/<repo-segment>, not cloud /workspace/<repo>
VAULT_ID / GCP profile errors Shared vault and GCP access profiles are cloud-oriented; self-hosted forbids fixed VAULT_ID and fails closed on unsupported GCP profiles

Full contract: docs/self-hosted-sandboxes.md.

PR / git outcomes

Symptom Fix
No PR at end Inspect parent tool create_final_pr events; permissions on pull_requests; branch push failures earlier in the stream
PR on wrong base Set pr.base in config or repo default branch expectations
Commit author unexpected git.authorName / git.authorEmail in config
Sub-issues missing Decomposition tool failures; Issues write permission; parent issue constraints

Dashboard / OIDC

Symptom Fix
Redirect loop / callback error OIDC_REDIRECT_URI exact match; clock skew; all OIDC vars set together
Everyone is viewer Add email to OIDC_ADMIN_EMAILS (exact match)
Blank / unstyled UI Run bun run build (CSS) in dev if dist/dashboard.css missing
Wrong language /locale/ja or /locale/en, or browser Accept-Language

Container / data loss

Symptom Fix
Settings reset every deploy Persist /data (or your DB_PATH volume)
DB locked / SQLITE busy Second replica writing the same file — run single writer
Permission denied under /data start.sh expects writable /data/app for app user (bun)

Still stuck?

  1. Capture run id, last event kind, and redacted logs (no PEM, no API keys)
  2. Reproduce on a small open issue in a disposable repo
  3. Compare against Installation checklist and Configuration security list
  4. Open an issue on ca-srg/maestro with steps + versions (bun --version, image tag)

Contributor path: bun run lint → bun run typecheck → bun test. Live E2E only with E2E=1 on a disposable repo (docs/e2e-setup.md).

maestro

日本語

Repository · Issues

Clone this wiki locally