Troubleshooting

Most failures fall into a handful of buckets: configuration is not ready, the repo is not trusted, the port is taken, admission rejected the configured tuple, or there is nothing to review. Each section below gives the symptom, cause, and fix using the same readiness and outcome language shown in Web, Ink, and CLI.

Symptom. Review actions stay disabled or show Configuration Not Ready with remediation text from the current readiness state.

Cause. A review starts only from a configuration whose product tuple passed admission. Until then, Diffgazer exposes the next safe action (create, inspect, select, test, update, or delete) instead of starting a review. An unverified configuration (Not verified, readiness conformance-pending) is not blocked: it can be selected and reviewed, and Verify stays optional.

Fix. Open Configure Provider in settings and follow the remediation for the reported readiness state below. Product-specific examples include Google Gemini and OpenRouter.

Symptom. Readiness is credential-invalid. The UI explains: The configured credential was rejected.

Cause. The hosted credential reference or stored literal value was rejected by the configured endpoint.

Fix. Update the configuration with a valid credential reference. Use Configure Provider, choose update, and replace the credential reference. Diffgazer never shows the rejected literal value in client-safe copy.

Symptom. Setup cannot proceed even though a key appears to work elsewhere.

Cause. The configured endpoint is not allowed for this product, so it does not match the credential's admitted tuple.

Fix. Choose an allowed endpoint for this product and transport, and verify it matches the credential you configured. Diffgazer does not substitute consumer or coding-plan products.

Symptom. Readiness is model-missing. The UI explains: The selected model is not available for this configuration.

Cause. The saved exact model ID is not present in the current admitted discovery result for the configured tuple.

Fix. Select an available exact model. Pin that exact ID, then start a review or Verify. Aliases and routing selectors are rejected.

Open the model picker in Configure Provider and choose a listed exact ID.

Symptom. A review ends with Schema Validation Failed and the message The provider response did not match Diffgazer's review schema. The review screen shows Model Incompatible with a Change model action that opens the providers page. Readiness turns conformance-failed with the explanation The exact review path did not satisfy the structured output contract. Starting another review with the same setup fails immediately and free, without contacting the provider: the start error reads Configuration Needs Attention and offers Open Providers.

Cause. The configured review path did not produce schema-valid output for the exact tuple. The failure is recorded against that exact tuple, so the next review does not pay to rediscover it.

Fix. Select a different model or change the configuration — any tuple change clears the recorded failure and the next review verifies inline again. Remediation message: Select a different model or update the configuration; reviews with this exact setup fail immediately until it changes. Verify can re-check it. Verify makes one small billed API call to the provider (typically under $0.02).

Symptom. A completed or failed review shows Usage unavailable with the detail This provider requires usage reporting, but none was returned.

Cause. The configured hosted product requires terminal usage reporting and the provider did not return it.

Fix. Check that the configured product and exact model support usage reporting for your account, then Verify the configuration or start a new review. Diffgazer does not infer usage from marketing pages or partial responses.

Symptom. A review ends with Budget Exhausted and the message The review stopped because a configured budget limit was reached.

Cause. The admitted execution plan hit a configured spend or token budget limit.

Fix. Reduce review scope, raise the configured budget if your workflow allows it, or choose a different admitted model or product. Diffgazer does not continue the run after the budget is exhausted.

Symptom. Readiness is unsupported. The UI explains: This configuration is not supported in the current environment.

Cause. The stored configuration names a product this build no longer supports — for example a product retired from the selectable roster.

Fix. Review the supported products and environment requirements. See the providers reference, then create a configuration for a supported product and delete the retired one.

Symptom. A review ends with Review Cancelled and the message The review was cancelled before it completed.

Cause. You cancelled the active session or deleted it while work was still running, or the server ended the session itself — an evicted session, an idle one, or a shutdown.

Fix. Open history before you rerun. Whatever the run's lenses had already produced is saved with it: the run is written with those partial findings, marked cancelled, and opens from history like any other saved review. A run that had produced nothing when it stopped is not saved at all. Diffgazer never resumes a cancelled run, so start a new review to cover the rest of the diff.

Symptom. A review ends with Review Timed Out and the message The review exceeded a configured time limit.

Cause. A dispatch exceeded its wall-time budget, or the provider accepted a request and sent only keep-alive whitespace (no answer bytes) for longer than the product's idle budget, or sent no response headers for longer than that budget (a gateway that answers non-streaming calls only when generation ends).

Fix. Review fewer files, choose a faster admitted model if one is ready, or adjust the execution limits for your workflow before retrying.

Symptom. Readiness is skipped. The UI explains: The live readiness check was intentionally skipped.

Cause. A required live probe was not run or could not run with the current prerequisites. A skipped probe is evidence only; it never enables a product.

Fix. Satisfy the live-check prerequisites, then run Verify again. Remediation code enable-live-probe means the configuration must be verified again after prerequisites are satisfied. In release smoke output, a skipped live probe is reported explicitly and does not count as passed.

Symptom. A review ends with Review Completed and the message The review finished with schema-valid findings.

Cause. The admitted configuration completed with schema-valid findings and a terminal receipt.

Fix. No remediation is required. Open the saved review from history if you need to revisit the results.

Symptom. A review ends with Transport Failed and the message The configured transport could not complete the review. When a hosted provider refused the request outright — a rejected credential (HTTP 401), refused access to the model or endpoint (403), exhausted billing or quota (402), an unknown model or endpoint (404), an oversized request (413), or a rate limit (429) — the review screen shows Provider Rejected the Request with the provider's own reason, for example Z.AI rejected the credential (HTTP 401)., and a Fix provider action that opens the providers page.

Cause. The admitted transport failed after review admission, for example because the network path dropped or the provider refused the request.

Fix. For a refused request, fix the credential, billing, or model on the providers page. Otherwise verify service availability, then start a new review (Verify checks the tuple without a full review).

Symptom. A review won't start. The request comes back with 503 / SETUP_REQUIRED, or 403 / SETUP_REQUIRED after a recorded conformance failure.

Cause. The selected configuration has an open item a review cannot resolve for itself — no configuration, an invalid credential, a missing model, an unaccepted notice, or an unreachable endpoint. Unverified structured-output conformance is not one of them: reviews start and verify it inline. A 403 means the exact tuple already failed structured output.

Fix. For 503, fix the named remediation and start the review again. For 403, select a different model or change the configuration; any tuple change clears the recorded failure. Both surface as Configuration Needs Attention with the server's remediation and an Open Providers action.

Symptom. A review returns 403 / TRUST_REQUIRED.

Cause. The current project lacks a matching read-files grant.

Fix. Open Trust and Permissions and grant repository access for the directory you are in.

Symptom. Setup or review returns KEYRING_UNAVAILABLE or KEYRING_READ_FAILED.

Cause. Diffgazer could not read stored credentials from the system keychain.

Fix. Unlock the keychain or switch to file storage in settings, then retry.

Symptom. A review stops with NO_DIFF.

Cause. The selected diff mode is empty.

Fix. Stage or edit files, or switch between staged and unstaged review.

Symptom. A review fails before any diff is read.

Fix. Run Diffgazer inside a git repository.

Symptom. A review stops before it starts, saying a file does not fit the selected model on its own. The message names the file, its estimated prompt tokens, and the model's context window.

Cause. A review too large for one call is split into batches of whole files, so total diff size no longer refuses a run — but batching splits between files, never inside one. A file whose own diff outgrows the context window cannot be dispatched, and the run is refused rather than truncated — a review of a diff you did not choose is worse than no review.

Fix. Exclude that file from the review, or select a model with a larger context window.

Symptom. A review starts, but warns that it is too large for one call: each lens reads it in a stated number of sequential batches, with an estimated input-token total for the whole run.

Cause. The estimated prompt exceeds the per-call budget — the smaller of the model's usable window and the effectiveCallTokenCap setting (default 49,152 tokens), which keeps each call at a size models read well. The diff is split into batches of whole files, a synthesis pass afterwards hunts for findings that span batches, and the review's budget envelope is scaled to the disclosed estimate so an admitted run is not stopped mid-review.

Fix. Nothing is required — the review runs. Cross-file findings between batches are only reachable by the synthesis pass, so they are less certain than in a single-batch review. For a sharper result, review fewer files at a time; if your model handles longer calls well, raise effectiveCallTokenCap in configuration.

Symptom. A review starts, but warns that the diff is large.

Cause. The diff fits one call but is over 512KB. One model pass over that much change finds less than several narrower passes would.

Fix. The review runs either way. For a sharper result, filter to the files you care about and review them separately.

Symptom. A review aborts saying the diff is past the 10MB ceiling.

Cause. A diff that size is almost always accidental: a committed lockfile, a vendored directory, or a generated bundle. No model choice helps.

Fix. Exclude the generated paths, or review specific files.

Symptom. The server fails to bind with EADDRINUSE.

Fix.

PORT=4000 diffgazer

Symptom. Bind fails with EACCES on a privileged port.

Fix. Use a port above 1024.

Symptom. Web mode cannot find the bundled SPA.

Fix. Reinstall or rebuild Diffgazer so the web assets ship with the binary.

Symptom. A review hangs or shutdown feels slow.

Fix. Press Ctrl+C in the terminal where Diffgazer is running. Increase DIFFGAZER_FORCE_KILL_DELAY_MS on slow machines if needed.

Check the FAQ or open an issue at https://github.com/b4r7x/diffgazer/issues with the visible error title and remediation text.