Troubleshooting

Connection & auth#

moa login / a command says “auto-bootstrap is unavailable”

Expected on the hosted product — it means the workspace is enrolled to a control-plane, so the CLI can't mint its own key. Onboard in the dashboard, create an API key on the Keys page (task scope), then run moa login and paste it (see Setup). Auto-bootstrap only applies to a standalone, single-operator workspace.

moa login can’t reach the workspace

The API URL is wrong or the workspace is down. Check the URL you entered (moa config set url …) and your network, and confirm the workspace is up. For self-hosted, make sure the service is running and the URL is reachable.

A connector shows “not connected”

Claude or GitHub isn't linked yet. Open the dashboard Settings and connect the provider (see Setup & authentication), then re-run moa status.

“Only the workspace owner can change global connectors”

Global connectors are owner-managed. Ask your org/workspace owner to set the Claude key or GitHub connection, or have them grant you the access — members can run workflows without owning the connectors.

A workflow didn’t trigger#

• Label name — issue→PR fires on the exact moa label. A different or misspelled label won’t trigger it.
• App not installed on that repo — the GitHub App must be installed and the repo selected. Add it in your GitHub settings or the dashboard Repos view.
• Webhook not delivered — if events aren’t arriving, check the repo’s webhook deliveries on GitHub; a failing secret or URL stops every trigger.
• Loop guard — repeated auto-triggers on the same item are capped to stop runaway loops, and Moa never auto-reviews its own bot’s commits.

Can’t wait for the trigger? Start the run directly from the CLI or the dashboard Dispatch view:

moa wf solve your-org/your-repo 7 --watch

A run failed or timed out#

The verify-gate failed

For writing workflows, the change must pass typecheck, lint, and build before a PR opens. If the gate fails, the run stops and no PR is opened — that’s by design. Open the timeline to see which check failed; the fix is usually in the agent’s diff.

The run hit the timeout or spend cap

Each run has a wall-clock timeout and a hard spend ceiling; crossing either cancels the run so costs can’t run away. A consistently capped task is usually too large — split the issue into smaller ones.

Review & merge#

Review posted nothing

Usually there’s nothing to review — an empty or already-up-to-date diff — or the push came from Moa’s own bot account, which it deliberately skips so it never reviews itself.

Auto-merge won’t merge

Merge waits for green checks and an approving review. If both look satisfied and it still won’t merge, it’s almost always branch protection — a required reviewer, a required status check that isn’t green, or required up-to-date branches. Resolve the protection rule and merge proceeds.

fix-CI didn’t turn the build green

Moa fixes the cause it can read from the logs. If CI stays red, the failure may be flaky, environmental, or need a secret Moa can’t see — open the run timeline and the CI logs to confirm, then re-run fix-ci or take it from there manually.

Getting diagnostics#

When you need more than a symptom match:

• moa status — operator, workspace, connector health, recent run counts.
• moa task get <id> — result, turns, and cost for a specific task.
• The dashboard run timeline — the per-step record of what happened.
• Add --json to most commands for machine-readable output you can inspect or log.