Skip to documentation

Reference

Troubleshooting

Resolve common setup, provider, runner, scheduling, and artifact failures.

Runner is offline

  1. Check the local process

    Confirm orchestrator run is active on the registered machine.

  2. Check Docker

    Confirm Docker is running and the kind cluster is available.

  3. Validate the token

    Restart the CLI and follow any prompt to replace a stale cached token.

  4. Inspect network output

    The runner requires outbound HTTPS and WebSocket access to the Orchestrator site.

Models are missing or stale

Run provider status, confirm the correct local credential exists, refresh the affected catalog, and restart the runner after environment changes.

orchestrator providers status
orchestrator providers refresh openai

Eligible work is not starting

Open the repository overview, agent editor, and workspace Runs page. Read the surfaced blocker before changing configuration.

  • The repository and target agent are enabled.
  • The trigger matches the issue, pull request, or schedule.
  • The runner is online with the required runtime image.
  • Repository and workspace capacity are available.
  • GitHub access and Project configuration remain valid.

Run finished without a verified artifact

The model may have completed useful work without producing the required GitHub outcome. Inspect events, validation output, GitHub permissions, and any existing artifact marker. A missing contract outcome is reported as failure, not success.

Frequently asked questions

Should I delete the kind cluster to recover a job?

Not as a first step. Inspect leases, runner output, and preserved workspaces before removing local state.

Why did changing an environment variable do nothing?

Provider credentials are read when the runner starts. Restart orchestrator run after changing them.

Why did a custom image fail to start?

Confirm the reference has a tag or digest, local or registry authentication is ready, the image was prepared in kind, and it implements the required agent contract.

Where should I look first after a failed job?

Open the run detail and read the final status, event timeline, failure reason, and artifact evidence before retrying.