Troubleshooting
Common ForgeDeck issues and how to resolve them.
Embed
<a href="https://docs.forgedeck.net/troubleshooting"><img src="https://docs.forgedeck.net/_api/public/orgs/db9cb8ff-b606-46cf-bbcd-02c8f8a9a3e2/spaces/6f417400-93ca-41a8-a914-df2ae3981dc6/pages/cff50916-47a7-4c7a-92f0-bc13350aad87/social-card.svg?v=3e7ae33eec8b" alt="Troubleshooting" width="600" height="315"></a>An agent CLI isn't detected
ForgeDeck only offers agents it finds on your PATH. Install the CLI (e.g. Claude Code, Codex, Gemini), then reopen the project. Terminals spawn a login + interactive shell so your full PATH is sourced.
A worktree won't merge
Make sure the task's branch is clean and the agent finished. If two tasks somehow share a scope, review them separately — and prefer ForgeSwarm, which assigns disjoint scopes automatically.
"Sign in to open terminals"
You're signed out, or your cached entitlement says so. Sign in from the Cloud tab. Offline, the app runs degraded (a limited set of terminals) until it can reconnect.
Logged out unexpectedly
Sessions are long-lived and slide forward on use, so this should be rare. If it happens, sign in again; a transient network blip during a cloud deploy can briefly interrupt account calls without ending your session.
Cloud features unavailable offline
By design — agents, swarm, voice, and workspaces require a connection. Plain local terminals keep working offline.
Still stuck? Email support@forgedeck.net.