> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sndbox.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Runner troubleshooting

> Diagnose pairing, presence, compatibility, environment, signatures, capacity, leases, and restart receipts.

## Pairing fails

Use a fresh one-time token only in `SANDBOX_PAIRING_TOKEN`. Confirm the printed device fingerprint in the control plane. Verify HTTPS and runner clock before retrying.

If `sudo` reports `sandbox-runner: command not found`, extract the complete release archive and run `sudo ./install.sh`. The binary should then exist at `/usr/local/bin/sandbox-runner`. Pair it as the service user with `sudo -u sandbox-runner env SANDBOX_PAIRING_TOKEN='…' /usr/local/bin/sandbox-runner --config /etc/sandbox-runner/config.toml pair`; using the absolute path also avoids `sudo` PATH differences.

If the service reports that the runner is not paired after a successful pairing attempt, check that pairing was performed as `sandbox-runner`, not `root`, and that `/var/lib/sandbox-runner/identity.json` is owned by `sandbox-runner`. Re-running the packaged installer repairs ownership of the dedicated data directory without replacing the identity or config.

## Runner is online but rejected

Routing diagnostics identify stale heartbeat, disabled/draining status, protocol or engine incompatibility, missing tag, wrong region, environment mismatch, runner capacity, or pool aggregate capacity. Do not remove a requirement merely to force selection.

## Command rejected locally

Check the control-plane signing key set, command expiry, nonce/time freshness, target runner/workspace/environment, revision content hash, required permission, connection restriction, and local allowlists. The human environment value must be development, staging, or production.

## Restart during work

The runner marks unfinished local execution failed and reports `runner_restarted_before_completion`. A previously completed durable receipt is acknowledged without re-execution. Lost-execution recovery may require manual review when an external side effect has uncertain outcome.

## Maintenance

Drain first and give the service manager at least the configured `drain_timeout_seconds` before killing the process.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.