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

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.

Uploading documents

An .rtf file uploads without complaint, and it is then read as plain text rather than parsed. Your analysis would see RTF control codes alongside the words. Convert to .docx or .txt before you upload.

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.

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.

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 one hundred and twenty codes. The cap is passed on a large corpus, later segments stop seeing the earliest codes, and synonyms appear. 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.

Silently dropped assignments in framework analysis. The same mismatch occurs in framework charting, and there the assignment is dropped without a log entry. 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, and its heading gives you the count for that document. 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.

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.