What causes "Could not resolve {resolver_type} '{entity_id}' to a folder" in infiniflow/ragflow?

Verify the dataset_id via GET /datasets/ before creating commits.

infiniflow/ragflow · error · ValueError

100

100

Error message

Could not resolve {resolver_type} '{entity_id}' to a folder

What it means

Raised by the folder resolver in the file-commit API when a URL entity (e.g. dataset_id) cannot be mapped to an internal folder id via _resolve_folder_id — the lookup returned None. Commits are scoped to folders, so an unresolvable entity means there is no commit target.

Source

Thrown at api/apps/restful_apis/file_commit_api.py:104

def _register_commit_routes(prefix, param_name, resolver_type=None):
    """Register all 8 commit endpoints for a given URL prefix.

    Args:
        prefix: URL prefix like '/folders/<folder_id>'
        param_name: The URL parameter name (e.g. 'folder_id', 'dataset_id')
        resolver_type: If set, resolve param_name → folder_id before calling logic
    """
    # Unique suffix for this call to prevent Blueprint endpoint name collisions
    _route_suffix[0] += 1
    _n = _route_suffix[0]

    def _resolve(entity_id):
        if resolver_type is None:
            return entity_id  # already a folder_id
        folder_id = _resolve_folder_id(resolver_type, entity_id)
        if folder_id is None:
            raise ValueError(f"Could not resolve {resolver_type} '{entity_id}' to a folder")
        return folder_id

    # ── Create commit ──────────────────────────────────────────────────────
    @manager.route(f"{prefix}/commits", methods=["POST"], endpoint=f"create_commit_{_n}")  # noqa: F821
    @login_required
    @validate_request("message", "files")
    async def create_commit(entity_id):
        folder_id = _resolve(entity_id)
        req = await get_request_json()
        try:
            commit = FileCommitService.create_commit(
                folder_id=folder_id,
                author_id=current_user.id,
                message=req["message"],
                file_changes=req["files"],
            )
            return get_json_result(
                data={

View on GitHub (pinned to 554fb1133a)

Solutions

Verify the dataset_id via GET /datasets/<id> before creating commits.
For new datasets, ensure normal document upload/folder init has run once so the KB folder exists.
Pass a real folder_id to the folder-scoped route variant if you have one, bypassing resolution.
Check the entity belongs to the authenticated tenant.

Defensive patterns

Strategy: validation

Validate before calling

from api.db.services.file_service import FileService

def folder_exists_for(dataset_id, tenant_id):
    root = FileService.get_root_folder(tenant_id)
    if not root:
        return False
    kb_root = FileService.get_kb_folder(tenant_id)
    return kb_root is not None

assert folder_exists_for(dataset_id, tenant_id), "KB folder not initialized - upload one doc first"

Try / catch

try:
    commit = create_commit(dataset_id, message, files)
except ValueError as e:
    if "to a folder" in str(e):
        raise ValueError(f"Unresolvable dataset id {dataset_id} - verify via GET /datasets/{dataset_id}") from e
    raise

Prevention

Always GET the dataset before issuing commit requests.
Initialize KB folders by completing one normal document upload on new datasets.
Never hardcode dataset ids; resolve them from creation responses.

When it happens

Trigger: POST /datasets/<dataset_id>/commits (or sibling commit routes) where dataset_id does not exist, belongs to another tenant, or the dataset has no root folder initialized yet (FileService.init_knowledgebase_docs never ran for that tenant).

Common situations: Using a copied/wrong dataset id, hitting the commit API on a freshly created dataset before its folder structure exists, or tenant mismatch after data migration.

Related errors

AI-assisted analysis of infiniflow/ragflow@554fb1133a (2026-08-15). Data as JSON: /api/errors/e19d2f15589767e3. Report an issue: GitHub.