Upload troubleshooting
The canonical version always lives at https://tavina.ai/docs/support/troubleshooting/uploads
Upload troubleshooting
Use this page when a customer reports a problem with file uploads, document processing, Source retrieval, or long-document answers.
Identify the state
Ask what Tavina showed after upload. Important states include:
- pending or extracting;
- extracted, chunked, or indexed;
- partial;
- failed;
- OCR-needed;
- encrypted/blocked;
- unsupported;
- image too large for visual analysis;
- image analysis stuck or unavailable;
- too many attachments or attachment limit reached;
- empty or no useful text found.
Do not tell the customer Tavina read the whole file unless processing and coverage evidence supports that.
Image analysis support notes
For photo uploads in chat, most valid phone, camera, and drone images up to 25 MB should be eligible for visual analysis after upload. Large valid JPEG-family camera or drone photos may be optimized into a smaller analysis copy before backend vision analysis, while the original attachment remains available for the conversation card and retention lifecycle.
If image analysis fails but the attachment remains visible, distinguish these cases:
- Still too large after optimization: ask the customer to upload a smaller copy or standard JPEG/PNG export. Escalate if the file is a valid phone, camera, or drone image near the normal size range and repeatedly fails.
- Unsupported image type or dimensions: ask whether the file is a valid JPEG, PNG, GIF, or WebP; if it came directly from a camera or drone, ask them to try a standard JPEG export.
- Attachment missing or unavailable: collect the conversation time, upload time, file name, and visible attachment state for escalation.
- Image analysis stuck or unavailable: newer releases handle temporary analysis unavailability automatically: if the customer’s assistant model can view images, the photo is delivered directly and the reply proceeds normally, so a successful reply during an analysis outage is expected behavior. If the model cannot view images, the message still goes through and the assistant asks the customer to resend the image later โ treat that resend note as the expected fallback, not a failure. For an analysis that is genuinely stuck (not a temporary outage), first suggest asking Tavina, in the same conversation, to retry the image analysis on the affected image. Tavina can re-run a stuck or unavailable analysis itself; a retry may still fail, so do not promise that the image will be analyzed. If the analysis stays stuck after a retry, the customer can use Discard stuck image and retry to answer the prompt without that image, or Start fresh conversation to rotate the server-side conversation context. Do not ask the customer to reload repeatedly as the only recovery step; if the same image or conversation stays blocked after a retry and the visible recovery options, escalate with the subscriber, approximate time, visible recovery message, and any visible image reference if support tooling exposes it. Plans with exhausted image-analysis quota still pause image analysis until the quota resets; that is expected billing behavior, not an outage.
Photo metadata can improve answers when present. Tavina accounts share available bounded image metadata โ such as capture time, camera/device, lens or exposure details, dimensions, orientation, and GPS/location โ with analysis by default because location can be useful for real-world image questions. Do not tell customers GPS is withheld unless they enable it. Instead, confirm whether their account or environment has an explicit opt-out/redaction setting, whether the photo actually contained metadata, and whether another app stripped or changed it. Do not promise that Tavina will always know where or when a photo was taken; metadata may be absent, stripped by another app, inaccurate, or intentionally disabled.
Do not ask the customer to send private images to support unless the normal support process and customer consent allow it.
Multiple attachments in one chat message
Tavina supports up to 20 files on one chat message. When a customer selects more than the limit, Tavina should give clear feedback and skip the extra files before upload or send. Do not treat a clear limit message as an outage.
For a report that only one of several attachments reached Tavina, collect:
- the approximate conversation time and subscriber/account;
- how many files were selected and how many stayed visible in the message;
- whether image thumbnails appeared separately and opened the expected full-size preview;
- whether non-image files appeared as file cards or chips;
- any visible upload, validation, or security-scan error text.
Escalate if accepted attachments remain visible but Tavina only responds to the first one, files disappear without a limit or scan message, an image thumbnail opens the wrong preview, or private upload paths/raw extracted text appear in chat.
Safe customer steps
Ask the customer to try:
1. a shorter filename with common characters;
2. a text or Markdown export when available;
3. an unencrypted PDF or EPUB;
4. a clearer scan or OCR-ready document if Tavina reports OCR-needed;
5. a smaller test file to see whether the problem is file-specific;
6. asking Tavina which Source and Catalog were created.
Citation or answer problems
If the customer says Tavina answered without citations, ask whether Tavina answered from:
- ordinary chat context;
- a selected Source;
- a Catalog search;
- targeted chunk retrieval;
- whole-Source traversal.
For important answers, the customer can ask Tavina to cite the chunks, pages, headings, or sections it used. If citation metadata is missing, Tavina should say so.
Long-document coverage problems
If the customer expected a whole-document summary, ask Tavina to report coverage:
- chunks or sections processed;
- chunks or sections skipped;
- failures;
- OCR-needed or encrypted/blocked sections;
- whether any artifacts were missing or purged.
Targeted retrieval is not whole-document review.
Escalation triggers
Escalate when:
- a supported document type repeatedly fails;
- valid camera or drone photos in the normal size range repeatedly report that analysis is still too large after optimization;
- image analysis repeatedly shows as stuck or unavailable after the customer uses the visible recovery options;
- Tavina reports success but cannot retrieve or cite anything;
- Tavina implies full coverage without coverage data;
- a Source is stuck pending or extracting;
- purge or retention behavior appears inconsistent with the Source state;
- the customer reports possible exposure of sensitive uploaded content.