Troubleshooting
“You are not signed in.”
Section titled ““You are not signed in.””Run forkstage login. If you are on a machine without a browser, make a token in the dashboard (Settings → API tokens) and forkstage login --token fst_….
The bake never becomes ready
Section titled “The bake never becomes ready”The bake waits for the recipe’s first http ready check. Three usual causes:
- The path does not exist.
ready: - http: app/means/, which many APIs answer with 404. Set it to a route that answers 2xx, such asapp/health. - The app listens on another port.
port:must be the port inside the container. - The app crashes on start. The bake’s error shows the last lines of
docker compose logs; fix the cause and bake again.
A bake gives up after 20 minutes with the logs.
“Could not reach https://api.forkstage.com”
Section titled ““Could not reach https://api.forkstage.com””Your machine could not talk to the control plane. Check your network, then status.forkstage.com. If the message mentions a timeout after five minutes, update the CLI (npm i -g forkstage@latest): old versions had a five-minute client limit.
The address does not open
Section titled “The address does not open”- The fork may have ended (idle or hard stop, or someone struck it).
forkstage lsor the dashboard says. DNS_PROBE_FINISHED_NXDOMAINin the browser while a phone on mobile data opens it fine: your network’s DNS resolver has a stale answer forforkstage.run. Point your machine at1.1.1.1or8.8.8.8, or wait; it clears within a day.- A corporate proxy that blocks wildcard subdomains: the address needs
*.forkstage.runallowed.
“This workspace already has N environments running (limit N)”
Section titled ““This workspace already has N environments running (limit N)””The running-at-once limit. forkstage down one you no longer need, or raise the limit in Settings → Limits.
Tests fail inside the fork but pass locally
Section titled “Tests fail inside the fork but pass locally”The tests run in the app’s runtime image, with what that image contains. If the final stage of your Dockerfile has no Maven, no dev dependencies or no browser, the test command cannot run there. Use a script that works with the runtime (a curl-based smoke test), or add the tool to the image.
The GitHub App posts nothing
Section titled “The GitHub App posts nothing”See When a pull request gets no comment. The dashboard’s Settings → GitHub lists recent runs and the failure reason for each.
“The pull request’s diff did not apply”
Section titled ““The pull request’s diff did not apply””The pull request’s base is too far from the snapshot. Bake again from main and push a new commit to the pull request (or close and reopen it).
Interactive shell closes at once
Section titled “Interactive shell closes at once”forkstage sh needs a terminal; it does not run from a pipe or a non-interactive CI step. Use forkstage exec -- <command> there.
Still stuck
Section titled “Still stuck”hello@forkstage.com reaches a person. Include the fork id or the stack name and the exact message.