langgenius/dify · error · ValueError

Invalid doc_type.

Error message

Invalid doc_type.

What it means

Raised in the metadata PUT handler when doc_type is not a key in DocumentService.DOCUMENT_METADATA_SCHEMA (datasets_document.py:1311). Allowed keys are the metadata document types (book, web_page, paper, social_media_post, ... and others). Same controller defect as 529: ValueError surfaces as HTTP 500 instead of a 400.

Source

Thrown at api/controllers/console/datasets/datasets_document.py:1312

        dataset_id: UUID,
        document_id: UUID,
    ):
        dataset_id_str = str(dataset_id)
        document_id_str = str(document_id)
        document = self.get_document(session, dataset_id_str, document_id_str, current_user, current_tenant_id)

        doc_type = req_data.doc_type
        doc_metadata = req_data.doc_metadata

        # The role of the current user in the ta table must be admin, owner, dataset_operator, or editor
        if not current_user.is_dataset_editor:
            raise Forbidden()

        if doc_type is None or doc_metadata is None:
            raise ValueError("Both doc_type and doc_metadata must be provided.")

        if doc_type not in DocumentService.DOCUMENT_METADATA_SCHEMA:
            raise ValueError("Invalid doc_type.")

        if not isinstance(doc_metadata, dict):
            raise ValueError("doc_metadata must be a dictionary.")
        metadata_schema: dict[str, Any] = cast(dict[str, Any], DocumentService.DOCUMENT_METADATA_SCHEMA[doc_type])

        document.doc_metadata = {}
        if doc_type == "others":
            document.doc_metadata = doc_metadata
        else:
            for key, value_type in metadata_schema.items():
                value = doc_metadata.get(key)
                if value is not None and isinstance(value, value_type):
                    document.doc_metadata[key] = value

        document.doc_type = doc_type
        document.updated_at = naive_utc_now()

        return SimpleResultMessageResponse(result="success", message="Document metadata updated.").model_dump(

View on GitHub (pinned to ef8544b173)

Solutions

1. Use a doc_type present in DocumentService.DOCUMENT_METADATA_SCHEMA (book, web_page, paper, social_media_post, or others).
2. Fetch the allowed set from the backend if exposed, or pin client and server versions together.
3. Server-side fix: raise InvalidMetadataError to return 400 instead of ValueError -> 500.

Example fix

# before
if doc_type not in DocumentService.DOCUMENT_METADATA_SCHEMA:
    raise ValueError("Invalid doc_type.")
# after
if doc_type not in DocumentService.DOCUMENT_METADATA_SCHEMA:
    raise InvalidMetadataError(f"Invalid doc_type: {doc_type}")

ALLOWED_DOC_TYPES = {"book", "web_page", "paper", "social_media_post", "others"}  # keep in sync with DOCUMENT_METADATA_SCHEMA
if doc_type not in ALLOWED_DOC_TYPES:
    raise ValueError(f"Invalid doc_type {doc_type!r}; must be one of {ALLOWED_DOC_TYPES}")

def is_known_doc_type(doc_type: str, schema_keys) -> bool:
    return doc_type in schema_keys

try:
    console.update_document_metadata(dataset_id, document_id, payload)
except HTTPError as e:
    if e.response.status_code >= 500 and "Invalid doc_type" in e.response.json().get("message", ""):
        # doc_type not in schema; correct and retry
        payload["doc_type"] = "others"
        console.update_document_metadata(dataset_id, document_id, payload)
    else:
        raise

When it happens

Trigger: PUT .../metadata with doc_type set to an unknown value (e.g. "unknown", "article") or a type from a newer/older backend version whose schema differs.

Common situations: Client hardcoded a doc_type not in this server's schema; version skew between frontend and backend; typo in the doc_type string.

Related errors

• Both doc_type and doc_metadata must be provided.
• doc_metadata must be a dictionary.
• invalid_metadata
• ${name} must be a non-empty array
• streaming response body missing

AI-assisted analysis of langgenius/dify@ef8544b173 (2026-08-12). Data as JSON: /api/errors/593412b8820569bd. Report an issue: GitHub.