Troubleshooting
Fixes for the problems you're most likely to hit, by symptom.
Start with the project header, which shows why a project isn't dispatching, then Activity (filter by the project), which logs every decision as action=… outcome=… reason=…. On a server, use journalctl -u harnessd.
Nothing gets dispatched#
| Check | Fix |
|---|---|
| Is the project started? | Press Start in its header. A paused project shows a play button. |
| Is the task in an active state? | New tasks often land in Backlog. Move it to Todo (built-in board), or check tracker.active_states matches your tracker's statuses exactly. |
| Does it have the required labels? | tracker.required_labels needs every label. |
| Is it blocked? | Blockers must be in a terminal state. ClickUp: "waiting on" dependencies; assignee: me also filters. |
| Is it parked or waiting on a linked task? | The card shows parked or waiting. Use Resume Retries or Stop Waiting on Linked Tasks. |
| Is there a preflight error? | The header shows it: missing_agent_credentials, docker_unavailable, links: …, and so on. See Other preflight blocks. |
| Is a budget reached? | daily_budget_reached and similar; dispatch resumes at midnight. |
| Are all slots full? | agent.max_concurrent_agents, per-state caps, or Settings → Limits. |
| Does the workflow validate? | Config errors show in the header and the Workflow inspector. |
To skip the poll interval, right-click the task and choose Dispatch Now.
Docker#
docker_unavailable: Docker is not running: start Docker Desktop, or set docker.enabled: false for this project.
The image isn't built: build harness-agent:latest (and the browser image, if you use the browser) on Sandboxes.
missing_agent_credentials: containers can't use your Mac's Claude login. Add an API key or a claude setup-token token in Settings → Credentials, or set up a gateway. If you added a Claude key under another variable name, the message names it: rename it to ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN.
sandbox network setup failed: another SI Fabrik process may own the sandbox network for the same data folder, or the subnet collides with one of your networks. Set HARNESS_SANDBOX_SUBNET to a free /20.
sandbox_policy: …: the project's WORKFLOW.md asks for less isolation than this host allows, such as no sandbox or sandbox.hooks: host. Fix what the message names, or, on the Mac, turn on Edit Project → Allow agents to run directly on this Mac. See The sandbox floor.
The agent can't reach something#
The run lists The sandbox blocked N hosts. Press Allow to add a host to the project's sandbox.network.allow. Remember:
- private addresses need the exact host name, not a
*.pattern; - cloud metadata endpoints can never be allowed;
- registries for private packages are added automatically when you declare them under
links.packages.
git push, npm publish and the like are refused: by design. github.com, registry.npmjs.org, registry.yarnpkg.com, crates.io and rubygems.org are read-only from Docker sandboxes, and the run lists the host with (read-only). SI Fabrik saves the task branch and opens the pull request itself. Git LFS downloads aren't supported yet. See Read-only GitHub and package registries.
A tool reports a certificate error for GitHub or a registry: it doesn't trust the egress proxy's CA. Most tools read one of SSL_CERT_FILE, NODE_EXTRA_CA_CERTS, CURL_CA_BUNDLE, GIT_SSL_CAINFO, REQUESTS_CA_BUNDLE, PIP_CERT or CARGO_HTTP_CAINFO, which the sandbox sets; point any other at /etc/harness-ca/bundle.pem. In a custom image, make sure nothing overrides these variables. See The proxy's certificate.
A tool can't connect, even in open mode: it ignores HTTP_PROXY / HTTPS_PROXY. Every Docker sandbox reaches the internet only through the egress proxy, so configure the tool's proxy setting (http://<proxy>:3128, the value of HTTPS_PROXY), or use a tool that honors the variables.
The connection closes during the TLS handshake: the TLS server name didn't match the allowed host, or the tool spoke plain text to port 443. Connect by the host name you allowed.
Credentials rejected#
The project header shows credentials_rejected: … with the credential to update. Replace it in Settings; SI Fabrik retries as soon as it changes. For claude setup-token tokens, run claude setup-token again.
Tracker errors#
| Error | Fix |
|---|---|
missing_tracker_secret | Define the token variable, for example CLICKUP_API_TOKEN, in Settings → Environment. GUI apps don't see your shell's exported variables. |
tracker_status (401/403) | The token is wrong or lacks access to the list or repository |
tracker_rate_limited | Wait; or raise polling.interval_ms |
| ClickUp shows no tasks | Check sprint_folder_id points at a Sprints folder with a current sprint, and the statuses match the list's |
Branches and pull requests#
No pull request was opened: the workflow needs a git: block with pull_request: draft or ready. For GitHub, gh must be installed and logged in (or HARNESS_GITHUB_TOKEN set). For other hosts, set git.provider or open the PR yourself.
The branch was saved under refs/harness/saved/…: the task branch had diverged in your repository, or was checked out there. Compare the two and merge by hand.
A workspace won't go away: its branch couldn't be saved, so SI Fabrik keeps it. Check the Activity log for the reason, fix it, then remove the workspace from the Workspaces tab.
refusing to use protected branch: task branches can never be main, master, develop, release/* and the like.
Hooks#
after_create failed: the new workspace is removed and the attempt retried. Check the hook's output in Activity (action=hook outcome=failed … reason=…). Remember hooks run in a sandbox by default, with no network outside an attempt.
A hook times out: raise hooks.timeout_ms (default 60 s).
The prompt#
template_render_error: the prompt uses an unknown variable or filter. Open the Prompt tab; the preview shows the error.
Previews and the browser#
Preview doesn't load: the dev server must listen on 0.0.0.0 inside the container (npm run dev -- -H 0.0.0.0 for Next.js, --host 0.0.0.0 for Vite). Check .harness/preview.log in the workspace.
The app never becomes ready: preview.ready must be a path that answers once the app is up; raise ready_timeout_s for slow builds.
Remote mode#
| Symptom | Fix |
|---|---|
harnessd: refusing to start: | Run harnessd check and fix each error: line |
no admin account | harnessd user add <name> --role admin |
admin '<name>' has no TOTP | harnessd user totp <name>, or turn off require_totp_for_admins |
… is accessible by group/others | chmod 600 the file named |
| Agents can't reach their tools | On Linux, tools_listen must be the Docker bridge address (172.17.0.1:7879), not loopback. On macOS with Docker Desktop, use 127.0.0.1. |
totp_not_enrolled when saving secrets | Enroll an authenticator on the server with harnessd user totp <name> |
bad_totp | The code is wrong, or was already used; wait for the next one |
| The app can't connect | The SSH tunnel isn't running, a wrong URL or port, or the pinned fingerprint changed |
A TLS error caused the secure connection to fail | The app connected to a non-loopback address with a self-signed certificate. Use an SSH tunnel; see Connect the app to a server |
cloudflare_not_configured on a server | Set the bridge URL and token in Server Settings → Sandbox |
git clone … failed for a project | The harness user needs a deploy key (SSH) or HARNESS_GITHUB_TOKEN / HARNESS_GITLAB_TOKEN (https) |