10. Troubleshooting

forbidden host, HTTPS required or forbidden origin from another computer. forbidden host: add the name you typed to the allowed host names. HTTPS required: use the HTTPS proxy and check that it sends X-Forwarded-Proto. forbidden origin behind a proxy: the proxy changes Host (or drops its port), or does not send X-Forwarded-Proto: https. If the server exits with "cannot listen on …", create the admin first with scf user create --admin.

Nothing is happening to an issue. First look at the health line under the top bar: it says when the Foundry itself is the problem. Then look at the Waiting card on the Dashboard — it says who has the next move (the badge at the start of the line), what to do and why. See also Why is nothing happening?.

A plan is waiting for approval. Its risk score is above 75, or the issue has Factory_review_plan. Read the plan on the issue and reply /approve (with notes if you like) or /reject with what to change.

The release pull request is a draft. The daily full test run or build failed on it; the daily report or release check starts with **Nothing needed from you** — it stays a draft until the checks pass. and has the failing output. It becomes ready again when a later report passes.

A run failed, or a watcher shows an error. The message says what happened, why, and what you can do first. Find yours in the table:

Then the message adds how to try again. A failed run can be resumed on its page to continue at the failed step, or (for an issue the Foundry watches) you remove the factory:failed label to start over. When the fix is a change to the flow (a larger budget), only a new run counts: a resumed run keeps the flow it started with. A change in Settings, such as the cost limits, also counts for a resume.

The raw text is still there, as a detail: under Raw details in the failure card on the run page, and inside each failed step of the Steps & transcripts list, under Error details on the watcher card, and inside the collapsed Details of the failure comment on the issue. The settings behind the messages are max_visits (attempts), limits.max_cost_usd (run budget), max_budget_usd (step budget) and timeout_sec (time limit). If a step only needs more time, raise timeout_sec and start over.

A watcher error names its repository and shows in the health line. For a connection problem, check the network, and that gh auth status works in the terminal where the Foundry runs and that you have access to the repository. Error details on the watcher card shows gh's first output line too. Check now on the Watchers page retries immediately. A "has not checked since …" line means no check finished for a long time (a check that takes over 10 minutes is given up).

"Codex is not installed" or "Codex is not logged in". Install Codex (npm i -g @openai/codex, or the ChatGPT desktop app) and run codex login. The Models page shows the status.

A local model says it is done but changed nothing. The model is not good at tool use. Try a coding model (qwen3-coder, gpt-oss) and use Try a model on the Models page.

A run stopped with "daily budget reached". It continues automatically the next day, or when you raise the budget and resume it.

The failure comment starts with what you need to do.

The Foundry failed, not the code. The run says so when an agent command was blocked, a marker could not be read, a push hit a protected branch or a setting is broken. Do what the sentence says (e.g. allow the command in the flow), then resume the run. The label stays the failed label.

A push was refused. Either the branch is protected, or the secret scan found something. A protected branch is a setting to change (Protected branches in Settings, or the flow's branch); the run then says the Foundry failed. A secret-scan finding is in the code: the step output lists the file, line and kind of secret.

Locked out. "This account is locked" after many wrong tries: wait 30 minutes, ask an admin to press Unlock on the Users page, or restart the server on the machine (the lock is in memory).

Reset password gave an error. The account may already have lost its password. If the Users page now reads "no password yet", use New link.

Change password gave an error. The password is not changed; your other sessions may be signed out. Try again.

Forgot the password. Ask an admin to use Reset password, or run scf user password <e-mail> on the machine. If no admin is left, run scf user create --admin. A set-password link that ended is replaced the same way. If the page said "sign-in is not working" after you sent the form, first try to sign in with the password you chose: it may have been set already.

The credential store is not working. Run scf credential check. Unlock the login keychain if it fails. If the key is gone (for example the data folder was copied from another Mac), delete credentials.json and add the credentials again. "An old key is still in the Keychain" means a removal failed after a delete or rotation; scf credential rotate-key clears it.

Tests fail for reasons unrelated to the change. Set the right command with the test_cmd variable, per repository in <repo>/.claude-factory/config.yaml. If the tests already fail before any change and the issue is meant to fix them, name them under ## Failing tests to fix; see Stories that fix failing tests.