Skip to main content

Troubleshooting

Cannot Login​

  • Verify username/password pair
  • Check whether bootstrap/join is completed
  • Confirm backend is reachable and auth config is valid

Quick checks:

curl -i http://localhost:8080/

Agent Cannot Start​

  • Confirm workdir is under allowed safe_paths
  • Check whether the agent is already running
  • Review server logs for process spawn errors

Typical causes:

  • Invalid workdir path
  • Missing executable/provider command
  • Process permission constraints

No Output or Stale Output​

  • Re-open the session and check status in agent cards
  • Check connection badge state in header (connected / connecting / reconnecting)
  • Switch to Debug/Raw output tabs for transport-level events
  • Verify server process is still alive

Recovery action:

  1. Keep the current failed session for evidence
  2. Create a fresh session with the same prompt
  3. Compare behavior and isolate environment differences

See also: Connection Status and Recovery

Worktree Problems​

  • Ensure selected repository path exists and is accessible
  • Check branch/ref availability when using create-worktree flows
  • Clean up abandoned worktrees if disk usage grows unexpectedly

Recovery Strategy​

  1. Keep the session for audit and replay
  2. Create a fresh run with a clean workdir/worktree
  3. Replay the prompt sequence in smaller steps
  4. If issue persists, verify deployment checklist and runtime config consistency