Troubleshooting

When something goes wrong in a town, start by asking the Mayor. It can see agent status, bead history and review feedback. This page covers the most common problems.

Agents Not Picking Up WorkCopy Anchor Link

Symptom: Beads stay in open status. No agents transition to working.

Common causes:

Quick fix: Ask the Mayor: "Why aren't beads getting picked up?", it can diagnose and often resolve the issue.

Container Not StartingCopy Anchor Link

Symptom: The container status shows errors or stays in "starting" indefinitely.

Common causes:

• Git clone failure (bad credentials, repo not accessible)
• GitHub App not installed on the repository
• Environment variables causing startup crash

Fix:

1. Check that the Hull GitHub App is installed on your repository
2. Verify your GitHub PAT is valid (if configured)
3. Remove any environment variables that might cause issues during container init
4. Use Graceful Stop or Destroy Container in Settings under Container; it restarts on the next dispatch

Git Authentication FailuresCopy Anchor Link

Symptom: Agents can't clone, push, or fetch. Errors mention "authentication failed" or "permission denied".

Common causes:

If the Mayor reports no_installation_found, the GitHub App needs to be reinstalled.

Review Loop / Stuck in ReviewCopy Anchor Link

Symptom: A bead cycles between in_review and in_progress repeatedly, or MR beads keep failing.

Common causes:

• The refinery finds issues the polecat can't fix (e.g., fundamental architecture problems)
• Missing PR URL on merge request beads
• Convoy feature branch deleted from remote

Fix:

1. Check the bead's event history for review feedback
2. If the feedback is a dead end, ask the Mayor to close the bead: "Close bead [id], the approach isn't working"
3. For stuck convoys, the Mayor can force-close: "Force close convoy [name]"

If the problem is a merge conflict, turn on Auto-resolve merge conflicts under Refinery, or resolve it yourself on the pull request. Use Retry Review on the merge queue item to run the review again.

The Mayor is UnresponsiveCopy Anchor Link

Symptom: Messages to the Mayor don't get responses, or the Mayor says it's "unauthenticated".

Common causes:

• The container is asleep and starting up
• The container token expired
• The Mayor hasn't been started yet

Fix:

1. Wait a moment; the container may be starting
2. Click Start Mayor if it's offered
3. In Settings under Container, click Refresh Token
4. If it still fails, use Destroy Container and try again

Convoy Stuck / Never CompletesCopy Anchor Link

Symptom: A convoy shows open but no beads are being dispatched, or it never reaches "landed".

Common causes:

• A bead this convoy depends on failed, which blocks the beads after it
• Convoy feature branch doesn't exist on remote
• Landing MR repeatedly failing

Fix:

1. Check convoy progress: which beads are closed? which are open/failed?
2. For a failed dependency, fix or close the blocking bead; the beads that depend on it then dispatch
3. Ask the Mayor: "What's blocking convoy [name]?"
4. If truly stuck: force-close the convoy and re-create it

Agent Permanently StuckCopy Anchor Link

Symptom: An agent shows as working but hasn't produced output for a long time.

Common causes:

• The agent's process stopped responding
• The agent is waiting on a network resource or API
• The agent is repeating the same steps

Fix:

1. Ask the Mayor: "Reset agent [name]"
2. This unhooks the agent from its bead and returns the agent to idle
3. Hull Fleet dispatches the bead again

High Failure RateCopy Anchor Link

Symptom: Many beads ending in failed status.

Common causes:

• Task descriptions are too vague (agents can't figure out what to do)
• The codebase has issues that prevent agents from working (broken build, missing dependencies)
• Model quality is too low for the complexity of the work

Fix:

1. Review failed bead descriptions, make them more specific
2. Ensure the repo builds cleanly (agents struggle with pre-existing broken builds)
3. Use a stronger model for complex work, for example hull-auto/frontier instead of hull-auto/balanced
4. Add custom instructions to guide agents: test commands, build steps, conventions

Getting HelpCopy Anchor Link

If you can't resolve an issue:

1. Ask the Mayor: it can diagnose most problems
2. Check the feed and Observability page: see what happened and when
3. Contact support: in Settings under Debug, copy the diagnostic information and email it to support@withhull.com