{"record":{"id":"d53f5e25dede1af2","repo":"langgenius/dify","slug":"invalid-metadata","errorCode":"invalid_metadata","errorMessage":"Invalid metadata value: {metadata}","messagePattern":"Invalid metadata value: (.+?)","errorType":"error_code","errorClass":"InvalidMetadataError","httpStatus":400,"severity":"error","filePath":"api/controllers/console/datasets/datasets_document.py","lineNumber":1054,"sourceCode":"        }\n    )\n    @console_ns.response(200, \"Document retrieved successfully\", console_ns.models[DocumentDetailResponse.__name__])\n    @console_ns.response(404, \"Document not found\")\n    @setup_required\n    @login_required\n    @account_initialization_required\n    @with_current_user\n    @with_current_tenant_id\n    @rbac_permission_required(RBACResourceScope.DATASET, RBACPermission.DATASET_CREATE_AND_MANAGEMENT)\n    @with_session(write=False)\n    def get(self, session: Session, current_tenant_id: str, current_user: Account, dataset_id: UUID, document_id: UUID):\n        dataset_id_str = str(dataset_id)\n        document_id_str = str(document_id)\n        document = self.get_document(session, dataset_id_str, document_id_str, current_user, current_tenant_id)\n\n        metadata = request.args.get(\"metadata\", \"all\")\n        if metadata not in self.METADATA_CHOICES:\n            raise InvalidMetadataError(f\"Invalid metadata value: {metadata}\")\n\n        metadata_fields = {\"doc_type\", \"doc_metadata\"}\n        if metadata == \"only\":\n            response = DocumentDetailResponse.model_validate(\n                {\n                    \"id\": document.id,\n                    \"doc_type\": document.doc_type,\n                    \"doc_metadata\": document.get_doc_metadata_details(session=session),\n                }\n            )\n            return response.model_dump(mode=\"json\", include={\"id\", *metadata_fields}, exclude_unset=True), 200\n\n        dataset_process_rules = DatasetService.get_process_rules(dataset_id_str, session)\n        document_process_rule = document.get_dataset_process_rule(session=session)\n        document_process_rules: Mapping[str, Any] = document_process_rule.to_dict() if document_process_rule else {}\n        segment_count = document.get_segment_count(session=session)\n        response = DocumentDetailResponse.model_validate(\n            {","sourceCodeStart":1036,"sourceCodeEnd":1072,"githubUrl":"https://github.com/langgenius/dify/blob/ef8544b173fd6cd7a8e71df2cab576e52bebbfbc/api/controllers/console/datasets/datasets_document.py#L1036-L1072","documentation":"Raised by GET /console/api/datasets/{dataset_id}/documents/{document_id} when the `metadata` query parameter is not one of the allowed METADATA_CHOICES {all, only, without} (datasets_document.py:1027). The offending value is interpolated into the message. HTTP 400, error_code invalid_metadata.","triggerScenarios":"GET .../documents/{id}?metadata=full, ?metadata=1, ?metadata=true, or any token outside the allowed set; the check at datasets_document.py:1053 rejects it.","commonSituations":"Frontend sending a localized or typo'd value; an SDK built against a different Dify version passing a new token; manual API call with a truncated or uppercased value.","solutions":["Use one of the accepted values: all (default), only, or without.","Send metadata=only to get just doc_type/doc_metadata, or metadata=without to omit them.","If calling from an SDK, pin the SDK version to match the backend's METADATA_CHOICES."],"exampleFix":"// before\nGET /console/api/datasets/{ds}/documents/{doc}?metadata=full\n// after\nGET /console/api/datasets/{ds}/documents/{doc}?metadata=only","handlingStrategy":"validation","validationCode":"ALLOWED_METADATA = {\"all\", \"only\", \"without\"}\nmetadata_param = requested or \"all\"\nif metadata_param not in ALLOWED_METADATA:\n    raise ValueError(f\"metadata must be one of {ALLOWED_METADATA}, got {metadata_param!r}\")\n# then: GET .../documents/{id}?metadata={metadata_param}","typeGuard":"def is_valid_metadata_param(value: str) -> bool:\n    return value in {\"all\", \"only\", \"without\"}","tryCatchPattern":"try:\n    doc = console.get_document(dataset_id, document_id, metadata=metadata_param)\nexcept HTTPError as e:\n    if e.response.status_code == 400 and e.response.json().get(\"code\") == \"invalid_metadata\":\n        metadata_param = \"all\"  # fall back to default\n        doc = console.get_document(dataset_id, document_id, metadata=metadata_param)\n    else:\n        raise","preventionTips":["Always pass the metadata query param explicitly from a constant set.","Pin the SDK version to the backend so accepted values match."],"tags":["metadata","query-param","validation","knowledge"],"backgroundTag":null,"analyzedSha":"ef8544b173fd6cd7a8e71df2cab576e52bebbfbc","analyzedAt":"2026-08-12T05:15:17.394Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}