Skip to main content
This page covers the most common issues teams encounter with Shipfox and how to resolve them quickly. For each symptom, you’ll find the likely cause and the steps to fix it.
Cause: No online runner with a matching label.Fix:
  • Check the runner process’s log for Runner session registered — the dashboard does not list connected runners yet.
  • Verify your workflow’s runner: label exactly matches a runner label (case-sensitive).
  • Ensure the runner process is running; a runner exits after its idle window unless SHIPFOX_POLL_MAX_DURATION_MS=0 is set.
  • In evaluation mode, remember the compose services do not execute jobs — a separate runner process must be started.
Cause: File is not in the correct location or has a YAML syntax error.Fix:
  • Confirm the file is under .shipfox/workflows/ and has a .yml or .yaml extension.
  • Run the file through a YAML linter (npx js-yaml your-file.yml).
  • Check that the file extension is .yml or .yaml.
Cause: Workflow YAML contains invalid or unsupported keys.Common mistakes:
  • Using loop, matrix, or branch — these are roadmap features not yet shipped. (${{ }} interpolation is shipped; writing {{ }} instead of ${{ }} is the common mistake.)
  • Setting env on an agent step — env is run-step only.
  • Using model, thinking, or provider on a run step.
  • No prompt on an agent step.
  • Using the reserved agent: key.
Fix: Review the Workflow Schema reference. Use the Authoring Prompt or Skills Package to get valid YAML from your coding agent.
Cause: Missing API key on the runner, or model/provider mismatch.Fix:
  • Verify the AI provider is configured in Settings → Agent providers with a valid API key.
  • Check that ANTHROPIC_API_KEY (or the relevant provider key) is set in the runner’s environment.
  • Confirm model and provider IDs are valid (see Model Providers).
  • Check the step log in the dashboard for error messages from the provider.
Cause: GitHub integration not connected, wrong trigger source, or repository is on GitLab.Fix:
  • Open Settings → Events. It lists every trigger event the workspace received. If your push appears with No workflows triggered, the workflow’s source does not match the connection’s slug (see Integrations). If the push does not appear at all, the webhook never reached Shipfox.
  • In the project settings, verify the GitHub repository is connected.
  • Push triggers only work with GitHub — GitLab is roadmap. Use source: manual, event: fire for non-GitHub repos.
  • Verify the GitHub webhook is registered (visible in your GitHub repo’s Settings → Webhooks).
Cause: The step referenced by restart_from doesn’t exist, appears after the gate step, or has no key:.Fix:
  • Add a key: field to the step you want to restart from (restart_from matches keys, not name: labels).
  • Ensure the keyed step appears before the gate step in the same job.
  • Use the exact name string — it’s case-sensitive.
Cause: Sentry integration not configured.Fix:
  • Go to Settings → Integrations → Sentry and complete the setup.
  • Verify the event value is one of: issue.created, issue.resolved, issue.assigned, issue.archived, issue.unresolved.
If you’re still stuck, check the run’s step log in the dashboard — it often contains the exact error message. Still need help? Reach out to the Shipfox team.