What causes "Unable to resolve RAGFlow dataset" in iflytek/astron-agent?

Pass an explicit, valid dataset_id to chunks_save instead of relying on resolution.

iflytek/astron-agent · error · CustomException

ChunkSaveFailed

ChunkSaveFailed

Error message

Unable to resolve RAGFlow dataset

What it means

chunks_save could not determine which RAGFlow dataset the target document belongs to. The strategy resolves dataset_id from the caller-provided value or a fallback (e.g. config/knowledge-base mapping); when _resolve_dataset_id returns None there is no dataset to address the RAGFlow API, so the save is aborted with ChunkSaveFailed.

Solutions

Pass an explicit, valid dataset_id to chunks_save instead of relying on resolution.
Verify the knowledge base -> RAGFlow dataset mapping exists (check the knowledge record in the DB and the RAGFlow API list-datasets).
Confirm RAGFlow config (API key/base URL/tenant) so _resolve_dataset_id can query the correct instance.
Re-create the dataset in RAGFlow and update the mapping if the dataset was deleted.

Example fix

// before
await strategy.chunks_save(docId="doc123", chunks=chunks)  # dataset_id=None
// after
dataset_id = await kb_service.get_ragflow_dataset_id(kb_id)
assert dataset_id, "knowledge base has no RAGFlow dataset"
await strategy.chunks_save(docId="doc123", chunks=chunks, dataset_id=dataset_id)

Defensive patterns

Strategy: validation

Validate before calling

async def can_resolve_dataset(strategy, dataset_id):
    return bool(await strategy._resolve_dataset_id(dataset_id))
# call chunks_save only if can_resolve_dataset(...) is True

Try / catch

try:
    await strategy.chunks_save(docId=doc_id, chunks=chunks, dataset_id=dataset_id)
except CustomException as e:
    if "Unable to resolve RAGFlow dataset" in str(e):
        handle_missing_dataset_binding(kb_id)
    else:
        raise

Prevention

Always store the RAGFlow dataset ID on the knowledge base record at ingestion time.
Alert on KB rows with empty dataset bindings.
Validate dataset existence after any RAGFlow migration.

When it happens

Trigger: chunks_save called with dataset_id=None and no resolvable fallback; the knowledge base record backing the dataset mapping was deleted or never created; environment/config lacking the RAGFlow dataset identifier.

Common situations: Document ingested outside the platform so no dataset binding exists; RAGFlow tenant changed and the old dataset ID no longer exists; a config key for the default dataset was renamed or left empty after deployment.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/09ef927613c06a4d. Report an issue: GitHub.

Appendix: source

Thrown at core/knowledge/service/impl/ragflow_strategy.py:489

            "chunkType": "RAW",
            "content": content,
            "question": None,
            "answer": None,
            "dataIndex": error_id,
            "imgReference": None,
            "copiedFrom": None,
        }

    async def _validate_chunks_save_config(
        self,
        doc_id: str,
        dataset_id: Optional[str] = None,
    ) -> str:
        """Resolve dataset for chunks_save."""
        resolved = await self._resolve_dataset_id(dataset_id)
        if not resolved:
            logger.error("Unable to resolve RAGFlow dataset for chunks_save")
            raise CustomException(
                CodeEnum.ChunkSaveFailed,
                "Unable to resolve RAGFlow dataset",
            )
        return resolved

    async def _validate_document_exists(self, dataset_id: str, doc_id: str) -> None:
        """Validate that the document exists in RAGFlow.

        Delegates to ``ragflow_client.get_document_info`` which uses RAGFlow's
        server-side ``id`` filter for an O(1) exact lookup (verified against
        v0.20.5 ~ v0.24.0). Raises ``CustomException(ChunkSaveFailed)`` on
        not-found or on any underlying error.

        ``get_document_info`` returns ``None`` only for the server's
        ``DATA_ERROR`` (code=102) "not owned / not found" path, raises
        ``ThirdPartyException`` for other non-zero codes, and lets transport
        errors propagate. The generic ``except Exception`` branch below wraps
        all raised errors into ``CustomException(ChunkSaveFailed)`` so the

View on GitHub (pinned to 5e758547a8)