Knowledge Base Troubleshooting
Comprehensive troubleshooting reference for document parsing, asynchronous training, index building, retrieval recall, and storage errors.
This manual compiles typical issues encountered during knowledge base ingestion, training, retrieval, and runtime execution, along with standardized resolution steps.
1. File Upload and Document Parsing
Issue: Parsing fails after uploading PDF or Word files
- Diagnostic Focus: Check whether the document is password-protected or restricted against copying; verify whether the PDF is a scanned image without a text layer.
- Actionable Fix: Decrypt encrypted files prior to upload. For scanned PDFs, run optical character recognition (OCR) locally to embed a searchable text layer before importing.
Issue: Table import reports "Invalid file format. Check the headers and content"
- Diagnostic Focus: Spreadsheet headers contain leading or trailing whitespace, typos, or multiple worksheets containing merged cells.
- Actionable Fix: Review Structured Dataset Template Specifications. Ensure headers are
q,a,index,metadata(indexmay repeat;metadatais optional), and Excel files contain a single worksheet with no merged cells.
2. Background Training and Index Construction
Issue: Collection status remains stuck on "Queue" or training stages (such as "Parsing" or "Index vectorization")
- Diagnostic Focus: Background worker consumers are inactive, Redis task queues are backed up, or model API keys have expired.
- Actionable Fix:
- Check your team's model quota and account balance.
- Verify network connectivity to upstream AI proxies or model providers.
- In self-hosted environments, inspect
fastgpt-app(andfastgpt-proin commercial deployments) container logs for training consumer health.
Issue: Training tasks retry repeatedly due to lost lock leases (RedisLeaseLostError)
- Diagnostic Focus: Chunk batch sizes are too large or remote embedding endpoints exhibit high latency, causing workers to exceed lease windows before committing.
- Actionable Fix: Inspect application container health, model latency, and lease-renewal logs. In self-hosted deployments, lower
VECTOR_MAX_PROCESS,QA_MAX_PROCESS, orVLM_MAX_PROCESSvia environment variables or Admin → System Configuration, then retry failed tasks from the Error list modal after recovery.
3. Retrieval Recall and Answer Quality
Issue: Search test returns zero results (empty recall)
- Diagnostic Focus: Lowest correlation thresholds are set too high, collections are not yet in a ready state, or an unmatched tag filter is active.
- Actionable Fix:
- Lower the Lowest correlation slider to 0.1 to probe candidate boundaries.
- Confirm collection status displays a green "Ready" badge and chunk text is readable.
- Check whether tag filters are active; clear tags temporarily and rerun the search.
Issue: Search hits target chunks, but the model answers "Information not mentioned"
- Diagnostic Focus: Search results may be missing from the AI Chat knowledge input, or reference and context budgets may truncate the evidence.
- Actionable Fix: Follow Connecting Knowledge Bases to Applications. Check the knowledge input and dedicated reference template, then balance reference, history, and output budgets within the model context window.
4. Storage and Infrastructure
Issue: Vector database exhausts connections or times out
- Diagnostic Focus: High-concurrency write batches deplete PGVector or Milvus connection pools.
- Actionable Fix: In self-hosted deployments, adjust database connection pool caps (such as
PG_MAX_CONNECTIONSorMONGO_MAX_LINK) or lower training concurrency; consult Deployment and Operations.
Issue: Uploaded source files vanish from object storage
- Diagnostic Focus: S3 / MinIO bucket lifecycle policies enforce aggressive expiration, or persistent volume mounts are missing.
- Actionable Fix: Review bucket retention policies and confirm persistent volume claims map to durable host storage.
5. Collection Tags and Access Permissions
Issue: Why is a tag missing from the Tag Filter dropdown?
- Diagnostic Focus: When an application or workflow node attaches multiple knowledge bases, the Custom Tag dropdown lists only shared tags whose names and attribute types match across every selected knowledge base.
- Actionable Fix: Confirm that each attached knowledge base defines the tag with the same name and attribute type; see Collection Tag System and Scope Filtering.
Issue: Where did legacy string tags go after upgrading?
- Diagnostic Focus: During upgrade, legacy string tags are migrated without data loss into an Option tag named
default_tag, preserving all existing file associations. - Actionable Fix: Rename
default_tagin Tagging to your preferred business label (such asCategory).
Issue: Does renaming a tag or option affect existing Tag Filters?
- Diagnostic Focus: Tag Filters match by tag name and option text.
- Actionable Fix: After renaming a tag or option in Tagging, update the corresponding filter conditions in your applications and workflows.
Issue: Why is the "Permission" entry missing from the file row menu, or why does the system prompt that dataset permissions are not enabled?
- Diagnostic Focus: The "Permission" menu entry is visible only to members with
Administratorpermission on that file, and the prompt indicates that the knowledge base is still in its default disabled state. - Actionable Fix: Ask a knowledge base administrator to enable collection permissions from a row's
··· → Permissionmenu and grant the required collaborator role; see Collection Permission Control.
Issue: Are custom permissions preserved after turning collection permissions off?
- Diagnostic Focus: Turning the switch off deletes all collection-level collaborator records in that knowledge base and reverts every collection to knowledge base inheritance; re-enabling generates fresh inherited snapshots from current knowledge base collaborators.
- Actionable Fix: Record custom grants for critical collections before disabling the switch.
Next Steps
- Holistic overview: Read Knowledge Base Full Lifecycle.
- Practice tuning: Explore Search Testing and Retrieval Parameters.
- Data maintenance: Review Data Maintenance and Incremental Updates.
Edit on GitHub
Last updated