Troubleshooting
Every error TraceCI can put in front of you, what it actually means, and what to do next. Errors are written as one actionable sentence rather than a stack trace, so the message you saw should map directly onto an entry here.
The run will not start
- No failed run found for this repository
There is no failed workflow run on the branch, or the branch name does not match. Branch names containing slashes are a common trip point.
Confirm the run is red in the Actions tab, then paste its URL instead of the repository name. A run URL removes the lookup entirely.
- Repository not found, or 404 from GitHub
The repository is private and the server has no GitHub token, or the name is misspelled.
Check whether a token is configured in settings. Without one, only public repositories are reachable.
- Could not read a repository out of that input
The text is not a form TraceCI recognises.
Use
owner/repo, a GitHub repository URL, atree/URL, or an Actions run URL. All four are accepted.
The run starts and then fails
- The logs for this run have expired
GitHub deletes run logs after a retention period, 90 days by default. The run still exists; its logs do not.
Investigate a more recent failure. TraceCI will not diagnose from the diff alone, because a diagnosis without the log is a guess dressed as a conclusion.
- That API key was rejected by the provider
Wrong key, wrong provider, or a key that has been revoked.
Keys are provider-specific — an OpenAI key will not work on a Groq model. Use Check key and model to test the pair directly.
- Rate limited by the provider
On a free tier this is almost always tokens per minute rather than requests. One investigation is three calls in about fifteen seconds, each resending the conversation.
Wait about a minute, or switch to a model with a higher limit. Re-running immediately is the most reliable way to hit it again.
- The key is valid but the account has no quota left
Billing or credit exhausted at the provider.
Top up, or switch to a model on a provider where you still have quota.
- The agent hit its step limit without reaching a conclusion
The model kept requesting tools. Usually a smaller model that cannot decide it has enough.
Switch to a stronger model. This is the clearest signal that the model, not the input, is the constraint.
The interface itself is wrong
- API unreachable, or the model catalog will not load
The backend is not running, the API base URL is wrong, or this origin is not allowed by the server's CORS configuration.
Open settings and re-check the connection. If the backend is up but the browser still cannot reach it, the cause is almost always that this origin is missing from
ALLOWED_ORIGINSon the server.- The trace stops moving for ten or fifteen seconds
Normal. Assembling context means downloading and unzipping a multi-megabyte log archive and resolving the baseline commit — all before any model runs.
The status stays on Investigating throughout, and the elapsed clock keeps running. If it exceeds about two minutes, stop it and retry.
- The run ended without a diagnosis
The stream finished but no structured result arrived, usually because the model produced output the schema could not accept.
Re-run, or switch to a model with stronger structured-output support. The trace is preserved either way.
- No cause found — TraceCI stopped rather than guess
The failing step's log contains no error-shaped line, so there is nothing to trace back to a change. The most common source is a run that never actually executed: a job cancelled while waiting for a runner, or a bot-raised run whose log is provisioning output.
This is the system working. If you had a specific red run in mind, paste its URL to pin the investigation to it; otherwise the repository's real CI is probably green.
- It diagnosed a run I did not mean
With no branch or run URL given, TraceCI takes the most recent failed run. Bot-raised runs — Dependabot and similar — are skipped automatically, but an older genuine failure can still be picked while newer runs are green.
The trace names the run it chose, and says so when newer runs have since succeeded. Paste a run URL for an exact target, or name a branch to narrow the search.
- An investigation id opens but has no server record
The checkpoint database was reset, the run was a replay, or you are on a different machine from the one that ran it.
The local copy still renders in full. Only the raw log window and diff summary, which live on the server, are unavailable.
The diagnosis is wrong
This is not an error state, so nothing will tell you about it. The procedure is the same every time and it starts with the inputs, not the reasoning:
- Open the full record and read the log window. Did it anchor on the real error, or on a warning above it?
- Read the diff summary. Is the baseline where you expected? A branch that has been red for a while produces a much larger diff than you would guess.
- Look at the tool calls. Did the agent read the file the traceback named, or did it never open anything?
- Check the confidence. A wrong answer at confidence 4 is the system working as designed; a wrong answer at confidence 9 is worth reporting.
Input problems outnumber reasoning problems