Question 1

How to fix 'Tenant not found' or 'Unable to serialize unknown type' errors after upgrading RAGFlow to v0.27.0?

Accepted Answer

This affects in-place upgrades from v0.26.x to v0.27.0 (fresh installs are unaffected). The v0.27.0 `Tenant` model adds a `tenant_ocr_id` column, but the startup migration only adds the legacy `ocr_id` column, so every tenant query fails with `column t1.tenant_ocr_id does not exist`. The exception is swallowed by `TenantService.get_by_id()`, surfacing as misleading 'Tenant not found' and `Unable to serialize unknown type: quart.wrappers.response.Response` errors on APIs like `POST /api/v1/datasets`.

Fix: manually add the missing column to your metadata database (verified workaround):

```sql
ALTER TABLE tenant ADD COLUMN tenant_ocr_id varchar(32);
```

After running this, dataset create/parse/retrieval all work normally. The permanent code fix is to add the column to the startup migration list in `api/db/db_models.py`:

```python
alter_db_add_column(migrator, "tenant", "tenant_ocr_id", CharField(max_length=32, null=True, index=True))
```

Note: related upgrade-path schema drift issues exist for `tenant_model.model_type` and `tenant_*_id` column types — check the startup logs for other 'Failed to create index' or missing-column warnings.

Question 2

How do I fix RAGFlow dropping Excel rows after a blank gap when the worksheet used range exceeds 10,000 rows?

Accepted Answer

Upgrade RAGFlow to a release containing the fix for issue #19185. The bug is in `deepdoc/parser/excel_parser.py`: `RAGFlowExcelParser.row_number()`/`_get_actual_row_count()` stops scanning at a large blank run when `max_row` is over about 10,000, so rows after the gap are silently omitted. Update from source and rebuild/restart, for example:

```bash
cd ragflow
git pull
docker compose up -d --build
```

If you cannot upgrade immediately, prepare the workbook before uploading: select the unused/blank rows and use **Delete > Entire row** (do not just press Delete/Clear Contents), then save so Excel resets its used range. Alternatively, copy the populated tables into a new workbook with no large blank gap between them, or reduce the worksheet used range below 10,000 rows. After saving, re-upload and reparse the file, then verify that the chunk/row count matches the expected number of rows.

Question 3

How to fix RAGFlow parsing UTF-8 BOM JSON or JSONL files into zero chunks or dropping the first record?

Accepted Answer

Upgrade RAGFlow to a release containing PR #19196, or patch `deepdoc/parser/json_parser.py`. In `RAGFlowJsonParser.__call__`, after decoding the file bytes and before JSON/JSONL parsing, remove one leading BOM character:

```python
if text.startswith("\ufeff"):
    text = text[1:]
```

This prevents `json.loads()` from receiving the invisible BOM and raising `JSONDecodeError`, which was previously swallowed and caused silent empty output.

Temporary workaround: remove the UTF-8 BOM before uploading:

```bash
sed -i '1s/^\xEF\xBB\xBF//' data.json
sed -i '1s/^\xEF\xBB\xBF//' data.jsonl
```

Or decode with `utf-8-sig` in Python:

```python
text = raw.decode("utf-8-sig")
```

After the fix, `.json`, `.jsonl`, and `.ldjson` files with a UTF-8 BOM produce the same chunks as equivalent files without a BOM, including preserving the first JSONL record.

Question 4

Why does RAGFlow retrieval return parent chunks and citations from the wrong dataset when using parent-child chunking?

Accepted Answer

Root cause (RAGFlow ≤ v0.27.1 with Elasticsearch): parent chunk IDs were hashed from the parent text only (`xxhash.xxh64(mom.encode("utf-8")).hexdigest()`), while every dataset of a tenant shares one ES index `ragflow_<tenant_id>`. Identical parent text in two datasets therefore maps to the same ES `_id`, and the later-ingested copy overwrites the parent's provenance fields (kb_id, doc_id, docnm_kwd, positions). Children stay distinct but point to the shared `mom_id`, and `retrieval_by_children()` fetched the parent by `_id` without checking dataset_ids — so a retrieval request restricted to dataset A could return dataset B's parent text, filename, and positions, corrupting citations even when answers look correct.

Fix (verified fixed, PR #19375): ChunkID generation is now namespaced per document (the hash includes the doc/kb scope, see common/format.go:191), so identical text in different documents or datasets gets independent IDs, and `RetrievalByChildren` filters/validates the fetched parent against the matched child's doc_id + kb_id and falls back to the child chunks on mismatch.

Action: upgrade to a release containing this fix and re-parse/re-index affected datasets so parent chunks are rebuilt with document-scoped IDs. Workaround on affected versions: avoid ingesting identical documents into multiple datasets under the same tenant, or place duplicated corpora in separate tenants (separate ES indexes) to prevent the ID collision.

Question 5

How to fix RAGFlow DeepDOC OCR missing most text on large sparse images?

Accepted Answer

Upgrade to a RAGFlow/DeepDOC build containing the #18509 fixes. The detector previously resized every image so its longest edge was only 960px; an 8000x8000 image was therefore scaled by 0.12, making small or sparse text undetectable.

The fix includes:
1. Raising `TextDetector` `limit_side_len` from 960 to 2048 in `deepdoc/vision/ocr.py`.
2. Tiling text detection for images larger than 4096px into overlapping 2880px regions, with coordinate mapping and cross-tile deduplication.
3. Applying the same tiled OCR detection path in Go's `inference.Client.OCRDetect`.
4. Keeping short OCR text instead of discarding it when no image2text model is configured.

If you cannot upgrade immediately, manually increase the detector limit as a temporary workaround:

```bash
grep -R "limit_side_len" deepdoc/vision
```

Change the 960 value in `deepdoc/vision/ocr.py` to 2048, then restart the OCR/RAGFlow service. This uses more memory and latency. For very large scans such as 8000x8000 images, prefer the tiled-detection fix or pre-split the image into overlapping tiles before OCR.

ragflow

Core Features

What It Can't Do

Use Cases

Tags

Getting Started

Similar Projects