13. Troubleshooting

Every failure QualiLens can show you is listed here, with its cause and its remedy. The messages are quoted as they appear on your screen.

Starting the app

A running server keeps the code it loaded when it started, however the folder changes afterwards. A QualiLens left running in a forgotten Terminal tab therefore keeps serving an old build after an update has landed in the folder, and the browser shows the old app while the folder holds the new one. The port check is the first thing the launcher does, before any environment work, so the report appears at once.

The launcher checks for the built artifacts rather than the folders. A first run that failed part way therefore retries cleanly on the next launch, rather than skipping the step that failed.

A line reading NOTICE: the data folder … appears to sit inside a cloud-synced directory is information, not an error: it says the sync service holds your database as well (the API keys in it are encrypted, and the secret that unlocks them is not in that folder), and points to QUALILENS_DATA_DIR in Getting Started. A line reading NOTICE: N saved API key(s) were encrypted in place appears once, on the first start after updating to 1.8, and names the secret file. A line reading NOTICE: the key secret … appears to sit inside a cloud-synced directory says that file is itself being synced, which defeats its purpose; QUALILENS_SECRET_FILE moves it. A line reading WARNING: The secret that encrypts your API keys could not be created means the app could not write that file: keys cannot be saved until it can, and the line names the path and the variable that moves it. A line reading WARNING: frontend/dist was built from different sources than frontend/src means the interface on disk is older than its source; run cd frontend && npm run build or ./package.sh.

The page refuses to talk to the app

Uploading documents

RTF is not supported — save the document as .docx or .txt first. is the refusal for an .rtf upload; RTF is markup, and reading it as text would feed control codes to the analysis.

The upload carries no filename. means the browser sent the file without a name; save it with a name and upload again.

Transcribing audio and video

Retry appears only on failed audio and video sources. A document that failed extraction was rejected at upload and never became a row. There is therefore nothing to retry, and you upload a corrected file instead.

Two messages may meet you if you press Retry at the wrong moment. Transcription is already in progress for this source means the transcription is running, and you should wait. Only failed audio/video transcriptions can be retried means the underlying file is gone, or the source is a document.

Configuring a project

Starting a run

Checkpoints

Model and provider errors

These appear as a failed run, with the error printed on the Run screen. You can resume all of them, and resuming skips the work already completed.

Errors about the shape of the response

These are QualiLens refusing output it cannot trust, rather than the provider failing.

<provider>/<model> returned no text (stop reason: ...) means the AI model produced nothing visible. On a model that reasons internally before answering, this usually means the token budget was consumed by that reasoning. Resume once. The model is a poor fit for this corpus if the error recurs, and a new project with a different model is the remedy.

<provider>/<model> output was truncated at the token limit; refusing to parse a partial JSON response means the response was cut off mid-structure. QualiLens refuses to repair it, because repairing a truncated analysis response would invent codes and quotes the model never produced. Resume, because the failure is often transient. The stage is producing more output than the budget allows if the error recurs at the same stage. That happens on unusually dense sources and on very large code sets, and the practical fix is to reduce the corpus or split it across projects.

<provider>/<model> returned N chars of malformed JSON — too large to repair means the response was complete but not valid JSON, and too long to repair safely. Resume the run.

JSON repair was itself truncated; giving up means the repair call also failed. Resume the run.

Gemini returned no candidates (block reason: ...) means a safety filter blocked the response. Qualitative data about health, violence, or abuse can trigger this. Resume once. A different provider is the practical remedy if the same segment blocks repeatedly.

Gemini stopped without a complete answer (finish reason: ...) means Gemini began an answer and then stopped it. SAFETY and PROHIBITED_CONTENT mean a content filter stopped it; RECITATION means Google withheld it for repeating source text too closely, which long verbatim quotes from published papers can trigger in a literature synthesis. QualiLens refuses the partial answer rather than parsing it. Resume once, and use a different provider if the same segment stops again.

Errors from the analysis stages

Reports

No report for this run yet means the run has not reached its final stage. Check the run’s status.

Updating the app

After an update, Your edited models.json differed from the update's; the outgoing copy was saved to … tells you where your model-catalog edits went so you can reapply them.

The coded-source reader

Source not found in this run's project means the source was deleted after the run completed. The excerpt and its quoted text remain in your stored report, and the document they came from is gone, so there is nothing to highlight.

Run not found means the run was deleted, usually because its whole project was.

A reader may open and show no highlights at all, with the code panel reading that there are no coded spans in this document. That means one of three things. The source may have contributed nothing to this run, which the excerpt count beside it in the report’s Sources section will confirm. Every code that touched the source may have been deleted at a checkpoint, because evidence on a deleted code is not shown. Or every quote from the source may have failed to locate, in which case the Not located in the text panel carries them, and its heading gives you the count.

Things that go wrong quietly

Five failures produce no error message. Check for them yourself.

Near-duplicate codes. The AI coder is shown the codes already in use so that it can reuse them, and that listing is capped at three hundred codes. The cap is passed only on a very large corpus; when it is, later segments stop seeing the earliest codes, synonyms appear, and the audit log records that the cap was reached. Merge them at your first checkpoint.

Dropped assignments in content analysis. The assignment is discarded rather than guessed at when the AI model names a code that does not match your codebook. The audit log records each drop, along with a summary at the end of the stage warning that your counts may undercount. Read the audit log if your totals look low. Short, distinctive code names attract fewer drops than long ones.

Dropped assignments in framework analysis. The same mismatch occurs in framework charting, and each drop is now logged with the name the model used and the quote, with a summary at the end of the stage. A framework code that is empty across every source is the symptom, and a shorter code name is usually the cure.

Short highlights in the coded document. The opening of a quote is located instead when the quote cannot be matched exactly or after normalizing typography, and the highlight then covers less than the quote. The passage is present, and the highlight is partial.

Excerpts that never reach the document. A quote that cannot be located at all is a different matter. It means the AI model did not copy the passage verbatim, which the coding instructions forbid. Those excerpts are gathered under Not located in the text in the reader, its heading gives you the count for that document, and the report marks each of them not located verbatim instead of quoting it. A handful is ordinary. A long list means the coder is paraphrasing. Check any quotation you intend to publish from that document against the transcript by hand before you print it.

Familiarization that read the opening only. A source longer than sixty thousand characters is summarized from its first sixty thousand, and the audit log says so for each such source. Coding covers the whole source; the memo that primes it does not.

Guard notes in the narrative. A Limitations section that ends with Citation guard: or Quote guard: is the report telling you that generated prose contained a citation or a quotation matching nothing in the corpus. Treat the sentences named as unverified.

When nothing here fits

The audit log on the Run screen records every stage boundary, every model call with its purpose, and every error with the tail of its traceback. Read it from the bottom up. The last entries before a failure usually name the source and the segment that caused it. The complete event history is in the database, and it outlives your browser session.