Last updated 2026-05-07

Troubleshooting

The most common things that go wrong, with the smallest fix that gets you unstuck.

"No such remote 'origin'" warning

Cause: the workspace is not a git repo or has no remote named origin. The runner tries to extract the repository name from git remote get-url origin.

Impact: none. The runner falls back to basename(workspace) and uses default ref / sha values.

Fix: none required.

Marketplace action download failures

Symptom: Failed to download action owner/repo@ref.

• Private repo: set GITHUB_TOKEN or GH_TOKEN in the runner's environment.
• Invalid ref: verify the tag/branch/SHA exists.
• Network issues: the runner has a 2-minute timeout on git clone operations.
• Stale cache: RUNNER_NO_CACHE=1 stax runner start forces re-download.

Sandbox creation failures

Symptom: Sandbox creation failed, running in-place.

• Dirty git state for worktree: run git worktree prune.
• Disk full: clean up /tmp/runner-sandboxes/.
• Permissions: ensure write access to RUNNER_SANDBOX_DIR.

Impact: the workflow runs in-place (no isolation). This is a fallback, not a hard failure.

Secret not resolving

Symptom: ${{ secrets.MY_SECRET }} evaluates to an empty string.

• Not set: check with stax secret list (or GET /api/secrets). For repo-backed secrets, check stax secrets list --env production.
• SOPS unavailable: install sops and run stax secrets status. The age CLI is optional, but the sops binary is required for decrypt/export/sync.
• No age identity: run stax secrets keygen, import an identity with stax vault age import, or set SOPS_AGE_KEY, SOPS_AGE_KEY_FILE, or SOPS_AGE_KEY_CMD.
• Runner mirror stale: after editing infra/secrets/prod.enc.yaml, run stax secrets verify and stax secrets sync runner.
• Local mirror encrypted without key: if secrets were saved with RUNNER_SECRETS_KEY and you start the runner without it, secrets cannot be decrypted. Use the same key.
• Wrong workspace: secrets are scoped by workspace path. Ensure the runner is serving the right one (look at the banner output).

Step fails with "command not found"

Cause: the tool is not installed on your machine. Unlike GitHub Actions runners, your local machine may lack specific tools.

Fix: install the tool. Setup shims will pick it up on the next run.

Job timeout

Cause: exceeded timeout-minutes (default 360 for jobs, 60 for steps).

Fix: raise the limit or debug why the step is hanging.

Node.js action fails with "entry point not found"

Cause: the action's dist/ directory is missing from the git clone (common with .gitignore-heavy repos).

Fix: the runner uses --depth 1 clones. If the action requires a build step, it won't work. Use a published tag that includes built files, or switch to a shimmed action.

"Address already in use" on startup

Something is already on port 4800. Find it with lsof -i :4800, then either stop it or start the runner on another port:

stax runner start --port 4900

Dashboard shows blank runs list

• Confirm the runner is up: curl http://localhost:4800/health.
• If you moved the runner, set RUNNER_URL when starting the dashboard.
• Check the browser network tab for /api/health and /api/runs responses.

Where to look for logs