FastGPTFastGPT

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 (index may repeat; metadata is 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:
    1. Check your team's model quota and account balance.
    2. Verify network connectivity to upstream AI proxies or model providers.
    3. In self-hosted environments, inspect fastgpt-app (and fastgpt-pro in 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, or VLM_MAX_PROCESS via 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:
    1. Lower the Lowest correlation slider to 0.1 to probe candidate boundaries.
    2. Confirm collection status displays a green "Ready" badge and chunk text is readable.
    3. 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_CONNECTIONS or MONGO_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_tag in Tagging to your preferred business label (such as Category).

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 Administrator permission 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 ··· → Permission menu 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

Edit on GitHub

Last updated