Troubleshooting
Every wait and every fault in ModernCI is named, either in the pull request's ci status or as an alarm (modernci call alarms, modernci call health). Find the name below. If it isn't here, write to [email protected] with the output of modernci call health.
Connecting
| You see | Why | Do |
|---|---|---|
A refused certificate when running modernci init, call or mcp | The install uses its own CA, and this machine doesn't trust it yet | Run modernci init <url> <CA fingerprint> < token-file with the fingerprint your admin gives you. The error names the CA the daemon serves and the line that trusts it |
curl https://… to an old daemon hangs | That daemon serves plain HTTP | Use curl -m 3 and the address modernci init --list shows |
| A command uses the wrong team | More than one login fits | Run it inside the repo's checkout, or pass --tenant |
The agent doesn't see done, claim, report, ask | MCP isn't registered, or the token lacks the agent scope | claude mcp add --scope user modernci -- modernci mcp, and ask for a token with agent |
| Failures don't arrive as turns in Claude Code | The channel isn't loaded | Start with claude --dangerously-load-development-channels server:modernci (interactive only; Team and Enterprise orgs must enable channels). Otherwise read modernci call my_work |
Waiting
| Status or alarm | Why | Do |
|---|---|---|
waiting on compute: … | No backend can take the check now. Each backend's reason is listed | Wait, or add capacity. modernci call capacity shows each backend's answer |
backend.none | No backend is configured and enabled for this team | The operator enables ModernCI compute for the tenant, or the team adds its own backend |
check.unplaceable | No backend has a capability the check requires: | Install the capability on a backend; the alarm names what is missing |
queued | Green, waiting behind the merge queue | Nothing: it merges in order |
superseded by #N | Another open pull request contains this one's head | Nothing: #N's result covers it |
blocked: <target> is red on <check> preview PR #94 | The target branch fails that check itself | Fix the target. The pull request isn't charged |
| Judging is paused | A release is being swapped in, or the repo is paused | Wait for the swap (running checks are adopted), or modernci call resume |
Failing
| You see | Why | Do |
|---|---|---|
| Red with a reproduce command | A check failed on this change | Run the command; your agent gets the same text |
Exit 127, backend.environment | A command isn't on the backend's PATH. ModernCI never reports this as a test failure | Install the tool, or name its directory in the backend's path |
| A test check fails with zero tests | It ran no tests, which counts as a failure | Fix the test filter or the build |
| A flaky test is quarantined | It failed in its suite and passed alone (cargo-nextest) | Fix it, then modernci call unquarantine |
| A conflict work item | The merge conflicts in source files | Rebase and push. Lockfile-only conflicts are resolved for you |
| A stale result | A green from an older engine or config | ModernCI re-tests it on its own. To force it: modernci call rejudge |
The install (operators)
| Alarm | Why | Do |
|---|---|---|
backend.isolation | The check user can read something of the daemon's, or is root | Fix run_as (see production readiness); no job runs there until it passes |
backend.unisolated | A local backend still runs checks as the daemon's user | Create the check user and set run_as |
stall.loop, pass.empty | The loop stopped making progress | modernci call health names the call it's stuck in. The supervisor restarts a daemon that stops answering |
watchdog.restart | The supervisor restarted the daemon | watchdog.json says why and how often |
hook.silent, hook.register | Webhooks aren't reaching the daemon | modernci call --tenant <t> webhook_sync. Register an https:// URL: forges don't follow the redirect from http:// |
update.rolled_back | A new release didn't come up healthy | It was rolled back to the previous binary. Report the version |