Skip to content

Docs / Troubleshooting

Troubleshooting

The agent is quiet, the PR will not merge, the box is offline — the checks that resolve most reports.

Start with the audit log. Every action is written before it runs, so "nothing in the log" and "the agent tried and failed" are different diagnoses, and telling them apart is usually most of the work.

The agent is not responding to issues

Work through these in order.

1. Is the App installed on that repository? An organisation-wide install still has a repository selection. Check Settings → Repositories in the dashboard: a repo that is not listed is a repo we never receive events for.

2. Is your account approved? Access is invite-only while we scale. An unapproved user gets a session limited to reading their own account and nothing dispatches. If you are on the waitlist, this is the answer.

3. Does .maintainer.yml parse? An invalid policy file is a hard stop, not a fallback to defaults — running with a policy we could not read would mean acting outside the bounds you set. Validate before committing:

curl -X POST https://api.developerz.ai/v1/repos/:owner/:repo/policy/validate \
  -H "Authorization: Bearer dev_pat_…" \
  -H "content-type: application/json" \
  -d @<(jq -Rs '{content:.}' .maintainer.yml)

4. Is there a model key on the account? BYOK is the only mode. With no usable key there is nothing to run the reasoning with. Check Settings → Model keys, and check the key is selected for the repository.

5. Did another bot get there first? If CodeRabbit, Copilot, Dependabot or Renovate is active on the thread, the agent defers by design — no bot-on-bot loops. Silence on a Dependabot PR is the rule working, not a failure. See Dependabot.

6. Are you paused or capped? A failed invoice pauses dispatch, and so does hitting your monthly spend cap. GET /v1/billing/usage reports both. See billing.

A pull request will not merge

The gates are machines, and all of them must agree:

  • CI green — every required check, not just the ones you remember.
  • Review passed — on paid tiers review can gate the merge.
  • Branch protections satisfied — required reviewers, up-to-date branch, linear history, signed commits, whatever you have set.

If all three look satisfied and it still has not merged, check that auto-merge is actually on for that lane. It is opt-in on free and OSS-verified accounts, and any path you marked human-merge always waits for a person, by design.

Fork pull requests are a special case in CI: jobs from forks are refused on fleet boxes, because a fork PR can carry an attacker-controlled workflow file. That check will not run on your hardware, and that is deliberate.

A box shows as offline

Liveness is a heartbeat every 30 seconds into a key with a 90-second TTL. Three missed beats and the box is gone from the fleet view.

systemctl status dz-runner
journalctl -u dz-runner -n 200 --no-pager

Common causes:

  • Outbound blocked. The box needs to reach nats.developerz.ai:4222 over TLS. It needs no inbound ports at all — if you are hunting for a port to open, you are hunting for the wrong thing.
  • Disk full. Workspaces live on the box. Below the 20 GiB floor, work stops.
  • The unit is not running. Restart=always covers crashes; it does not cover a unit that was stopped or masked.

A box that is draining is not offline: it keeps beating until in-flight work settles, then lets its key lapse.

A CI job stays queued forever

Jobs are matched to boxes by label. A job whose label no enrolled box satisfies waits until one appears or the workflow times out — it is never silently run somewhere else. Check the label in your workflow against the sizes your boxes report, and check the box has the ci capability (it is an opt-in).

A webhook is not arriving

  • Deliveries retry on a ladder out to 24 hours; after nine failures the webhook is marked unhealthy and stops. Check GET /v1/webhooks/deliveries — the ledger keeps the last 100 attempts with the response excerpt.
  • An endpoint that resolves to a private or loopback address is refused, with a deliberately generic reason. Put a public proxy in front of an internal service.
  • Verify the signature against the raw body. Re-serializing the JSON before hashing is the single most common cause of "the signature never matches".

See outbound webhooks.

You are getting 429s

60 reads and 10 writes per minute, per token or session; 300 per minute per IP before authentication. Honour the retry-after header. There are no RateLimit-* headers to budget against — see rate limits.

Still stuck

Have the audit-log entry (or its absence), the repository, and the timestamp ready, and contact us. For anything security-sensitive, use the responsible-disclosure address in security rather than a public issue.