{"record":{"id":"4715b10f9c8552fb","repo":"infiniflow/ragflow","slug":"invalid-uuid-format","errorCode":"invalid_uuid_format","errorMessage":"Invalid UUID format","messagePattern":"Invalid UUID format","errorType":"validation","errorClass":"PydanticCustomError","httpStatus":null,"severity":"error","filePath":"api/utils/validation_utils.py","lineNumber":346,"sourceCode":"        Invalid cases:\n            >>> validate_uuid1_hex(\"not-a-uuid\")  # raises PydanticCustomError\n            >>> validate_uuid1_hex(12345)  # raises PydanticCustomError\n\n    Notes:\n        - Uses Python's built-in UUID parser for format validation\n        - UUID version is no longer enforced (v1, v4, v7, etc. all accepted)\n        - Hyphens in input strings are automatically removed in output\n    \"\"\"\n    try:\n        if isinstance(v, UUID):\n            uuid_obj = v\n        elif isinstance(v, str):\n            uuid_obj = UUID(v)\n        else:\n            raise TypeError\n        return uuid_obj.hex\n    except (AttributeError, ValueError, TypeError):\n        raise PydanticCustomError(\"invalid_uuid_format\", \"Invalid UUID format\")\n\n\nclass Base(BaseModel):\n    \"\"\"Strict base model that rejects unknown request fields.\"\"\"\n\n    model_config = ConfigDict(extra=\"forbid\", strict=True)\n\n\nclass RaptorConfig(Base):\n    \"\"\"Dataset parser configuration for RAPTOR summary generation.\"\"\"\n\n    use_raptor: Annotated[bool, Field(default=False)]\n    prompt: Annotated[\n        str,\n        StringConstraints(strip_whitespace=True, min_length=1),\n        Field(\n            default=\"Summarize the paragraphs below without inventing facts or changing numbers.\\nOutput exactly two parts in the same language as the source:\\n1. First line: a concise title only.\\n2. Following lines: a concise summary of the content.\\nDo not output labels, Markdown headings, bullet points, or any other commentary.\\n\\nParagraphs:\\n{cluster_content}\"\n        ),","sourceCodeStart":328,"sourceCodeEnd":364,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/api/utils/validation_utils.py#L328-L364","documentation":"Raised by the shared UUID normalizer in api/utils/validation_utils.py when a request field that must be a UUID (or its .hex) is neither a UUID instance nor a string parseable by Python's UUID(). Any non-string type, or a malformed string (wrong length, bad hex characters, misplaced hyphens), triggers it. The validator accepts any UUID version and returns the canonical hex form.","triggerScenarios":"Sending a dataset_id/document_id like \"abc\", \"123e4567e89b12d3a45642661417499z\" (bad hex char), an empty string, or a numeric type where the API model expects a UUID field; also passing a UUID with garbage after it, e.g. \"550e8400-e29b-41d4-a716-446655440000 extra\".","commonSituations":"Copy/pasting IDs with trailing whitespace or a newline; using an internal DB integer ID where the public API expects the UUID; passing JSON numbers because the ID was stored as a number in the client; truncating UUIDs in logs and reusing them.","solutions":["Send the full canonical UUID string, e.g. \"550e8400-e29b-41d4-a716-446655440000\" (hyphenated or 32-char hex both work; hyphens are stripped automatically).","Verify the value came from the API's own response (id field) rather than an internal/legacy identifier.","Trim whitespace and confirm length is 32 hex chars (plus optional hyphens) before sending."],"exampleFix":"# before\n{\"document_id\": \"doc-12345\"}\n\n# after\n{\"document_id\": \"550e8400e29b41d4a716446655440000\"}","handlingStrategy":"validation","validationCode":"import re\n\ndef normalize_uuid(value: str) -> str | None:\n    \"\"\"Return 32-hex canonical form, or None if invalid.\"\"\"\n    cleaned = value.strip().replace(\"-\", \"\")\n    return cleaned if re.fullmatch(r\"[0-9a-fA-F]{32}\", cleaned) else None\n\nif (uid := normalize_uuid(raw_id)) is None:\n    raise ClientError(f\"not a valid UUID: {raw_id!r}\")","typeGuard":"function isUuid(v: unknown): v is string {\n  return typeof v === \"string\" && /^[0-9a-fA-F]{32}$/.test(v.replace(/-/g, \"\"));\n}","tryCatchPattern":"try:\n    model = MyRequest(dataset_id=raw)\nexcept ValidationError as e:\n    if any(err[\"type\"] == \"invalid_uuid_format\" for err in e.errors()):\n        log.warning(\"bad UUID %r — refetch id from the API\", raw)","preventionTips":["Always take IDs from API responses, never retype them from logs.","Strip whitespace/newlines before sending IDs.","Validate with a 32-hex regex client-side before every call."],"tags":["uuid","validation","pydantic","rest-api"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}