# Knowledge Base Troubleshooting

> Comprehensive troubleshooting reference for document parsing, asynchronous training, index building, retrieval recall, and storage errors.

Source: https://doc.fastgpt.io/guide/dataset/faq
Last Updated: 2026-11-12

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](https://doc.fastgpt.io/guide/dataset/template). 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](https://doc.fastgpt.io/guide/dataset/connect-application). 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](https://doc.fastgpt.io/self-host).

### 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](https://doc.fastgpt.io/guide/dataset/collection_tags).

### 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](https://doc.fastgpt.io/guide/dataset/collection_permission).

### 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](https://doc.fastgpt.io/guide/dataset/lifecycle).
* Practice tuning: Explore [Search Testing and Retrieval Parameters](https://doc.fastgpt.io/guide/dataset/test-retrieval).
* Data maintenance: Review [Data Maintenance and Incremental Updates](https://doc.fastgpt.io/guide/dataset/update-data).
