Files & Knowledge troubleshooting
Use this guide when a file uploads but cannot be used, a Knowledge source never becomes ready, or retrieval misses expected content.Upload failed
Check:- file size and type
- account/organization upload policy
- storage limit
- active session
- current platform health
Upload succeeded but content is unavailable
The file can exist before extraction or indexing is complete. Check processing state.Source is stuck processing
Determine which stage is stuck:- extraction
- chunking
- embeddings
- indexing
Source is FAILED
Inspect source-specific error metadata when available. Fix unsupported/corrupt input, integration access, provider problems, or storage issues before retrying.
Source is ready but query misses it
Check:- active Project/organization context
- requester permission
- direct distinctive query
- retrieval candidates
- reranking/filtering
- context/result limits
- model interpretation
Repository is stale
Refresh the connected repository/revision after major changes. Confirm Starfire still has integration access and is indexing the intended branch.Duplicate sources
Avoid repeated re-upload as a troubleshooting technique. Duplicates can create confusing retrieval results while leaving the real ingestion problem unresolved.Citation points to wrong material
Treat that as a retrieval/citation-verification issue. A source existing in the run is not enough; the cited passage must support the claim.Retrieval debugging
Follow the full ingestion-to-model diagnostic chain.