Troubleshooting
Find what you see in the left column, then the cause and the fix. Messages are quoted as the product shows them in English.
"Check once" or the pre-run fails
For a project connected to a GitHub repository, when "Check once" or a waiting run's pre-run fails, the platform's AI first fixes the test connection itself from the check's result and log (see the pre-run). Below is what to look at when it can't, or when you'd rather fix it yourself.
| Symptom | Cause | Fix |
|---|---|---|
| The agent's log says a key or variable is missing, or its model rejects the key | A project secret is missing, or its name differs from the one in review.yaml | "Secrets" lists the values review.yaml and the tests read by name, and marks the missing ones: click a name to fill it into the form, then add its value. See project secrets. |
services failed to start (docker compose up exit 1): env file /work/repo/.env not found | The repository's Compose file reads .env through env_file, and a .env holds real keys and is rarely committed, so the sandbox's clone has none | If the test doesn't need those services (the agent's own web service, say, while the test calls its function directly), take services out of review.yaml. If it does, write services as named services (image, ports, env, ready), with values from secrets or runner_env. The platform's draft and the AI's both leave such a Compose file out. See services. |
The agent can't connect to its tools or database: connection refused on 127.0.0.1 | The service's port isn't published on 127.0.0.1, or the server in the container listens only on localhost | Publish it as "127.0.0.1:47591:47591" in your Compose file, or list it under ports; make the server listen on 0.0.0.0. See services. |
command not found, or the attempt ends with "agent exited … without a JSON result" | agent.command is wrong, runs from the wrong folder, or the agent doesn't print its result | The command runs from the repository root (an image: its WORKDIR). The last line on standard output must be one JSON object with text. See the command driver. |
exec format error, or a package that can't be found for aarch64 | The sandbox's architecture doesn't match your code or image | Nothing for you to do. The platform spots it in the pre-run's log and pre-runs again on the other architecture by itself, leaving the project's setting alone. If that passes, it switches "Settings" → "Sandbox" → "Architecture", says so on the page, and offers "Switch back". When both fail, both results are shown, and the code or image itself needs a look. See architecture. |
| "Pre-run failed: the test didn't reach the agent" | The agent didn't start or didn't take the task | Check agent.command or agent.endpoint and the agent's lines in the sandbox log. |
| "Pre-run failed: the platform can't see the agent's tool calls" | The agent calls its tools directly, not through the tool proxy | Make the agent read its tools' address from attach.base_url_env, or its MCP configuration from REVIEW_MCP_CONFIG. See attach. |
| "Pre-run failed: the attachments didn't reach the agent" | The agent doesn't read the test's files | Pass {{files_json}} in the command, or read REVIEW_FILES and REVIEW_FILES_DIR. |
| "Pre-run failed: can't tell whether the agent uses a model to decide" | The agent doesn't report its model calls | Include usage.model_calls in its last JSON line, or in the HTTP reply. |
The agent's calls to the Responses API (/v1/responses) get an HTTP 400 error that names something the platform's model doesn't take | The project has no OPENAI_API_KEY, and its model is Gemini 3.8 Flash, which the platform answers through chat completions. OpenAI's hosted tools, files by file_id, stored prompts, conversation and background mode need OpenAI's own servers. With previous_response_not_found, the response named is over 6 hours old, was sent with store: false, or the platform restarted since | Use function tools for hosted ones, and send the files' content and the whole conversation in input. Or switch the project to a GPT model in its header. See your agent's model. |
| "Pre-run failed: the judge model on the test runner doesn't work" | The judge model has no key, or the model name is wrong | Use a judge model the platform provides, or add its key. See judge model keys. |
| "Pre-run failed: the agent didn't finish within each test's limit" | budget.per_attempt is too small for the task | Raise minutes or model_calls in budget.per_attempt. |
| "A value is still missing before the check: …" | A value review.yaml reads by name (a secret-looking env_passthrough name, the state reader's or the data reset's address variable) is in neither the project's secrets nor runner_env | Add it under "Secrets". For a value that isn't secret, click "Write into runner_env". If you know the agent does without it, click "Check once anyway". |
| "There's no confirmed test yet, and checking with the platform's own question needs an identity variable the sandbox has…" | No confirmed test, no identity variable, and review.yaml is only in the repository | Add a synthetic test identity to review.yaml's runner_env (for example AGENT_TEST_USER: test-user-1), or click "Let AI finish and check". |
| "The test runner is offline. A pre-run runs on the test runner…" | The local test runner isn't running | Run reviewctl runner start on the test machine. |
review.yaml is refused
The web editor won't save a file that wouldn't load, and names the line and field. On a test machine, reviewctl doctor exits 3.
| Symptom | Cause | Fix |
|---|---|---|
| "the YAML is malformed near line …" | Uneven indentation, a colon with no space after it, or an unclosed quote or bracket | Fix that line. |
| "unknown field. Check the spelling, or remove it" | A field the schema doesn't have, at any level | Check the reference. |
| "a key is written out here" | A secret value in the file | Remove it, add the name to agent.env_passthrough, and store the value under "Secrets". |
| "the start command is missing" | driver: command without agent.command | Add the command. |
| "this field is missing" or "should be …" | A required field is absent or has the wrong type | See the field in the reference. |
| A sandbox run ends with "The repository has no .reviewctl/review.yaml" | Neither the repository nor the overlay has the file | Save one to the overlay in the wizard under Targets, or commit one. |
The virtual machine never reached the platform
| Symptom | Cause | Fix |
|---|---|---|
| "The first VM didn't reach the platform within 12 minutes of starting… started another by itself" | The virtual machine didn't boot or couldn't reach the platform. It isn't charged. | Nothing for you to do: the platform deletes it and starts another by itself (the same test, started by the same person). |
| "The VM the platform started again by itself didn't start either…" | The second one didn't start either | Nothing for you to do: the platform has sent the job id and both VMs' boot logs to our engineers, and we'll be in touch once we know why. Neither was charged. |
| "The cloud couldn't create the VM the first time…" | The cloud couldn't create the VM just then (quota, no capacity in the zone…). It isn't charged. | Nothing for you to do: the platform tries once more a minute later; if that fails too, our engineers are told, as above. |
| "Waiting for a sandbox slot…" | As many sandboxes are running as the organization policy allows | Wait, or have an owner raise "Sandboxes running at once". See limits. |
A run was lost or cut short
| Symptom | Cause | Fix |
|---|---|---|
"The VM disappeared mid-run", or a job ends as lost | The sandbox or the test runner stopped answering while running | Reset the test backend, since what ran may have changed data. Start again and tick the box confirming you've checked. Until someone does, automatic and API runs are refused (409 lost_job_unacknowledged). For a sandbox run whose review.yaml uses only backends inside the sandbox, the platform checks it itself and the job page says "The platform checked", with no box to tick. The rule is under after a lost run. |
| "The run hit the time limit for one run (organization policy)…" | The run took longer than "Longest run" | What ran is reported as usual. For a sandbox run, click "Run the N that didn't run" on its report: the platform starts a new sandbox for only those attempts and reads the results into the round report (see fill-in runs). Next time run fewer tests, or have an owner raise the limit within the plan. |
| "Preparing the environment stalled: … printed nothing for 15 minutes (last line: …)" or "Preparing the environment reached the time limit: …" | A step of the sandbox's preparation printed nothing, most likely a package's install script downloading or building something the agent doesn't use, or waiting on an address it can't reach | Install only what the agent needs, or skip the install scripts it doesn't need; or click "Let AI finish and check", which changes it that way from the log. See preparation that stalls. |
| "Preparing the environment stalled: the dependencies were installed, and saving the dependency cache …" (or "restoring the dependency cache …") | The platform's own step of saving or restoring the dependency cache stopped; the dependencies themselves are fine | The platform's problem: nothing to change in the test connection, and it isn't charged. Try again in a while. |
| "The same problem 2 times running: … it has stopped" | Two checks of "Let AI finish and check" hit the same error, and changing the connection again by itself would most likely end the same way | Read that check's log, or edit the connection files by hand; click "Try again" for one more round of the AI. Nothing more is charged once it stops. |
| "This month's sandbox hours are used up…" during a run | The monthly hours ran out | See limits reached. |
| A run says "Didn't run" | The test never reached the agent, so the verdict can't be trusted | Fix the connection as above, then run again. |
| "This project already has a job queued or running…" | One run at a time per project | Wait for it to end, or cancel it. |
Signing in
| Symptom | Cause | Fix |
|---|---|---|
| "The sign-in link doesn't exist, was already used or has expired: ask for a new one" | A sign-in link works once, within 15 minutes | Ask for a new one on the sign-in page. At most 5 are sent to one address an hour. |
| "The invite code doesn't exist, was already used or has expired" | An invitation works once, within 14 days | Ask an owner to invite you again. |
| "Sign-up isn't open right now…" | Only people already in an organization can sign in | Ask an organization's owner to invite you. |
| "Sign-up isn't open right now… If you already have an account…" after GitHub or Google | None of the verified emails on that account is your address here | Add and verify your address on that GitHub or Google account, or sign in with your email. |
| "Signing up needs an activation code…" or "That activation code isn't right…" | Signing up a new account needs the activation code | Email admin@nice2.io for one, enter it under "Activation code" and click again. The same sign-up keeps working for 15 minutes. |
"Too many activation code tries…" (429) | 5 tries on one sign-up, or 20 in an hour from one network | Start again on the sign-in page, or try again an hour later. |
| "Sign-in was cancelled…" | It wasn't approved on GitHub's or Google's page | Click the button again. |
| "This sign-in expired or was already used…" | More than 10 minutes passed after you clicked, or you started another sign-in in a different tab | Click the button again, in one tab. |
| "That account has no verified email…" | GitHub or Google hasn't verified any email on that account | Verify one there, or sign in with your email. |
| "That GitHub or Google account is already linked to another account here…" | That account already signs someone else in | Use another account, or accept the invitation with "Accept and sign in". |
"Accept the Terms of Service and the Acceptable Use Policy in the browser first…" (403 terms_required) | The terms in force haven't been accepted, for example after they changed | Open the platform in the browser, tick the box and click "Accept and continue". The CLI works again straight after. |
| "The CLI token is invalid, revoked or expired…" | Unused for 90 days, signed in over a year ago, or revoked | Run reviewctl login again. |
| The CLI sign-in code is refused | The code works for 10 minutes | Run reviewctl login again for a new code. |
Uploading a run
| Symptom | Cause | Fix |
|---|---|---|
| "refusing to upload …: possible secrets in …" | A file in the run still holds a secret value or a key-shaped string | Find where the agent prints it and stop it; name secret variables so they are masked (see redaction). |
| "The run bundle unpacks to more than 512 MB", "… more than 10000 files", or a file over 64 MB | The run's evidence is too big | Make the agent and the data reads write less. Nothing of a refused bundle is kept. |
| "run … is already archived with different content" | A run with this id was uploaded with other contents | Runs can't be changed once uploaded; start a new run. |
| "… in the run bundle is not in the form reviewctl writes" | The run's files were edited, or reviewctl is out of date | Upgrade reviewctl and run again. |
"Not signed in: run reviewctl login --api <url> first" | No saved sign-in and no REVIEWCTL_TOKEN | Sign in, or set REVIEWCTL_API_URL and REVIEWCTL_TOKEN. |
GitHub and images
| Symptom | Cause | Fix |
|---|---|---|
| "This GitHub App installation is connected to another organization…" | The installation belongs to another of your organizations | In that organization, open any project's "Connect a GitHub repository" and click "Disconnect" beside the account in step 1; then install it again here. |
| "Your GitHub account can't access this installation…" | You're signed in to GitHub as someone else | Sign in to GitHub as the account that installed it, or an owner of that GitHub organization. |
| "The install link expired (it lasts an hour)…" | More than an hour passed | Click "Install the App on GitHub" again. |
| "This installation covers no repositories…" | No repository was selected on GitHub | Add repositories in the App's settings on GitHub. |
| "The image couldn't be read: …" | The registry needs a sign-in or refused it, the tag doesn't exist, the registry can't be reached, or the manifest format is too old | Save a "Registry sign-in", check the reference, or push the image again with a current docker or buildx. |
| "The image has no … build; it has …" | The architecture setting names one the image lacks | "Check once" runs on the architecture the image has by itself, and when it passes the platform switches the project's "Architecture" to it (you can switch back). If starting a test is refused, set "Architecture" to "Auto", or build the image for that architecture. |
Limits reached
| Symptom | Cause | Fix |
|---|---|---|
A launch is refused with 402 ("This month's free credit of $5.00 is used up…", "This period's Pro credit of $20.00 and your balance are both used up…", "This month's spending has reached the … cap…", "…sandbox hours are used up…", "Your prepaid balance is used up…", and so on) | The plan or the policy doesn't allow new runs now | See when tests can't start. |
| "Your plan allows at most …; the organization policy can only be set within that" | A policy value above the plan's cap | Set it within the cap, or change plan. |
"Too many requests; retry after …s" (429) | More than 20 sign-in requests a minute from one address | Wait the time given. |
| "Too many tries: try again in a minute" | Too many "Try it" runs in a minute | Wait a minute. |
| "The assistant reached today's spending limit…" | The assistant's daily limit is used | Use it again tomorrow. |
| "The platform has paused this organization…" | We paused the organization | Contact us to resume. |
Contact support
Write to admin@nice2.io with:
- The job id (
job_…, in the address of the run's page,/j/job_…) or the run id (run_…, in the report's address,/r/run_…). - The project's name or id, and what you did and when.
- The message you saw, copied as text.
Never send secret values: we don't need them, and we can't read the ones you stored. Check service status for known incidents first.