Academy
7. Troubleshooting, Limits and Best Practices
Handle failed documents, understand embedding credit costs and document limits, and apply best practices for sharp retrieval.
When you upload a document to a knowledge base, it is split into chunks and indexed in the background. A progress bar tracks the process, and the document becomes searchable once its status shows as "processed." However, some documents may fail — usually because of unsupported formats, corrupted files, or excessive size. When this happens, the failed status appears next to the document. Your first step is to re-upload a cleaner or smaller version of the file. If multiple documents are stuck in a failed state, your administrator can trigger a bulk reprocess from the RAG admin panel. Always check which file types your admin has enabled — the upload zone will reject unsupported files with a clear message.
Indexing documents is not free: it consumes embedding credits proportional to the size of the content being processed. Larger documents cost more credits. Searching an already-indexed base, on the other hand, is lightweight and inexpensive. Your plan and administrator settings also cap the maximum number of documents per knowledge base. Before building a massive base, check your available credits and document limits to avoid surprises mid-project. If you hit a cap, consider splitting content across multiple focused bases — this also improves retrieval quality.
Sharp retrieval depends on how you organize and chunk your content. Documents are split into chunks before indexing; larger chunks preserve more context per result, while overlap between chunks prevents ideas from being cut at boundaries. The defaults work well for most documents, but you can tune them: increase chunk size for long, structured texts (e.g., legal contracts or manuals), and decrease it for short-answer content like FAQs. Equally important is base organization — keep one knowledge base per topic rather than dumping everything into a single catch-all base. Focused bases return more relevant passages.
Test your knowledge base with real user questions, not just keywords. Open the built-in search field on the base page, type a natural question, and inspect the returned passages. If results miss the mark, add more relevant documents or revisit your chunk size and overlap settings.
If you use MCP import mode, your base auto-syncs with the connected integration. This means content stays fresh without manual re-uploads — but also means embedding credits are consumed each time new or updated content is re-indexed. Monitor your credit usage accordingly.
Open one of your knowledge bases and use the built-in search field to test three real questions your team would ask. Review the returned passages: are they relevant and complete? If not, try adjusting chunk size or adding a missing document, then test again.
Failed documents are usually a format or size issue — re-upload a cleaner version or ask your admin to reprocess them. Indexing costs embedding credits proportional to content size, and document limits are set by your plan and admin. For the best retrieval: keep one base per topic, tune chunk size only when needed, and always test with real questions using the built-in search field. These practices ensure your AI answers stay grounded, accurate, and relevant.