Troubleshooting

Installation fails

For a 401 or 403 from GitHub Packages, check the registry entry and your own classic token’s read:packages scope. A 404 can mean your account lacks package access or the scope points at the wrong registry. Ask the package owner to check your account access. Never paste tokens into graph prompts or logs.

If the server cannot load better-sqlite3 after a pnpm install, repeat the install with --allow-build=better-sqlite3. If pnpm has no global bin directory, run pnpm setup and open a new shell. Follow installation.

The first turn fails

Read the command or harness named in the failure. Check its version and login in the shell that starts the server. The server does not inherit credentials exported after it started. Restart it after changing environment variables, then retry the stopped node. Check the selected model and provider if authentication succeeds but model discovery fails.

Codex rejects the working folder

Codex requires a Git repository. Check the server-side working folder selected in the project’s folder list. For the practice folder, run git init ~/orbital-practice, then confirm git -C ~/orbital-practice rev-parse --show-toplevel prints that folder. Select this repository in Orbital and retry the failed step.

Validation rejects the graph

Run orbital validate with the explicit saved file path. A missing entry needs the ID of a declared node. Unknown attributes often mean retired syntax or a typo. A missing prompt file or import needs the companion at the path relative to the file naming it. A read-before-production error needs an earlier producer on every incoming path, not a fabricated default.

For choice routing, give each conditioned edge a distinct weight and cover every accepted choice or provide a fallback. See each node type and conditionals.

Starting reports missing inputs

Fill in the goal and every required graph input on the new-run page. Optional inputs end in a question mark in the declaration. If the graph is not the one you expected, check for a custom graph shadowing a file of the same name. Confirm the project includes the folder containing the graph.

A run appears stopped

Check whether the server restarted while the run was executing. Open the transcript to identify the last active node. Resume uses a continuation when available; Retry starts a fresh visit. Neither is the same as starting an unrelated run. See how the engine works.

A failed step does not take its fallback

That is intentional. Failed stages take matching conditioned edges only. With no matching failure route, the run holds for the operator. Add an explicit failure route if recovery belongs in the graph, or resolve the cause and retry. A failed terminal ends the run and records a terminal failure.

A probe that keeps retrying is still inside its observation node. Check GitHub authentication, repository access and the diagnostic before changing graph edges.

A worktree remains after cleanup

Inspect worktree.status and the cleanup step. Orbital retains all checkouts if removal could lose work. Commit and push needed changes, or complete the appropriate PR action, then retry cleanup. Do not delete the directory to make a run look successful.

Return to getting started to isolate installation problems with a harmless prompt.