Troubleshooting

Honest answers to the problems people actually hit. When in doubt: the deployment's event trail and the run's event/log stream almost always say what happened.

Login & access

I can't log in

• Sign-in is "Sign in with GitHub" — you need a GitHub account. If the OAuth dance completes but you land logged out, your browser is likely blocking the session cookie (forginate_session). Allow cookies for the product host and retry.
• Sessions are JWTs with an expiry; if you've been away a while, just sign in again.

My API calls return 401 / 403

• 401: the token is missing, malformed, expired, or revoked. PATs must be sent as Authorization: Bearer fgn_pat_.... The plaintext secret is shown only once at creation — if you lost it, revoke and create a new one.
• 403 insufficient_scope: your PAT lacks the needed scope (read, write, admin). Note that managing tokens themselves requires a session or an admin-scoped PAT.
• 403/404 on org routes: check the org slug in the URL and that your user is actually a member of that org with a sufficient role.

Runs

My run looks stuck

• Open the run's live event stream first. A run showing a "delayed" badge is not stuck: the LLM provider hit a wall (rate limit, overload, credit exhaustion) and the run is deliberately waiting it out, retrying the same call every 15 minutes for up to 24 hours without re-spending anything. Leave it alone; it resumes exactly where it stopped.
• A run with no events at all may still be waiting for a worker pod to schedule. If nothing happens for many minutes, cancel it (.../runs/:runId/cancel or the UI button) and start again.
• Runs have a hard wall-time deadline and a dollar cost cap; hitting either ends the run with a recorded reason rather than silently spinning.

A run failed — will it retry?

No. Runs never auto-retry (a retry that redoes paid LLM work would double your cost). Read the failure reason in the run detail, fix the cause if it's on your side, and re-run the step.

Where do I see what a run cost?

Every LLM call emits a usage event with exact token counts, and the run shows a live cost while executing. Org-wide totals are on the Usage page (GET /api/orgs/:orgSlug/usage) and in Billing.

Deployments

Start with the deployment detail page: status, lastError, the event trail, and recent logs are all there.

Stuck in planning

• The AI planner failed repeatedly → the deployment moves to failed with "use Re-plan to retry". Hit Re-plan, optionally adding guidance.
• "No image available" → the project has no linked GitHub repo and no image ref. Connect a repo (or supply an image) and re-plan.
• AWS targets: planning can also wait on the vended account still being created (see below).

Stuck in deploying

• Agent target offline? Check the target's status: degraded means no heartbeat for 2+ minutes, disconnected for 10+. Commands can't be applied until the agent reconnects — check the agent pod in your cluster and its outbound connectivity. Dispatch retries automatically (a command is re-sent after 10 minutes if no result came back).
• Image pull failures show up in live_status pod reasons (ImagePullBackOff, ErrImagePull). Verify the image exists and is pullable. For AWS targets pulling from a private registry (e.g. GHCR), the platform's registry pull credentials must be configured; public images pull anonymously.

App deployed but unreachable

• Check the deployment's endpoints. On k8s, that's the ingress host the planner created — DNS for that host must point at your cluster's ingress. On AWS, each Fargate task gets a public IP on the app's port.
• Wrong port is the most common cause: the planner defaults to 8080 unless told otherwise. If your app listens elsewhere, say so in the instructions (e.g. "port 3000") and re-plan.
• degraded status means readiness probes are failing — read recent_logs for the app's own startup errors (crash loops, missing env, OOMKilled shows in pod reasons).

How do I stop / undo things?

• Stop works from any non-terminal state and scales the app to zero; data and the plan survive, Start brings it back.
• Teardown deletes the workload (on AWS: the ECS service; the account, cluster, and roles remain for reuse).
• Cancel a run from the run detail; pause a build from the request's build screen.
• A deployment record can only be deleted once it is torn_down, separated, or failed — this is deliberate, so nothing keeps running unaccounted.

An incident/bug report appeared I didn't file

That's the deployment monitor: the agent fingerprinted a recurring error in your running app and auto-filed it as a bug-kind improvement request with the log sample attached. Approve it to have the factory fix it, or reject it.

AWS (vended account) targets

• A new target sits in pending while the account is vending (AWS account creation takes a few minutes). It flips to connected when the account is active.
• Vending can fail terminally (email already used for another AWS account, organization account limits). The error is recorded on the account; fix the cause (e.g. a unique root email) and retry, or contact support.
• AWS infrastructure costs are pulled monthly from Cost Explorer and billed through Forginate with the service margin — they appear in Billing, separate from token usage.

Self-hosting notes

The saas/ control plane is developed against a Kubernetes cluster and installed via the Helm chart in deploy/helm/forginate (CNPG Postgres, Redis, MinIO required; see deploy/README.md and docs/ runbooks in the repository). Self-hosting the full multi-tenant control plane is possible but not a supported, documented product path today — expect to read code. Common gotchas:

• The SPA is served by the api-gateway from its bundled static assets; there is no separate web deployment.
• GitHub login, the GitHub App, and Stripe each need their own credentials wired via the chart's secrets (see the repo's runbooks).
• The orchestrator needs RBAC to create Jobs in its namespace; runner pods intentionally mount no service-account token.

Still stuck?

Include the org slug, project, and the run or deployment id (plus the lastError and relevant event-trail entries) when you ask for help — those identifiers let anyone reconstruct exactly what happened.