infiniflow/ragflow · error · PydanticCustomError

invalid_uuid_format

invalid_uuid_format

Error message

Invalid UUID format

What it means

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.

Source

Thrown at api/utils/validation_utils.py:346

        Invalid cases:
            >>> validate_uuid1_hex("not-a-uuid")  # raises PydanticCustomError
            >>> validate_uuid1_hex(12345)  # raises PydanticCustomError

    Notes:
        - Uses Python's built-in UUID parser for format validation
        - UUID version is no longer enforced (v1, v4, v7, etc. all accepted)
        - Hyphens in input strings are automatically removed in output
    """
    try:
        if isinstance(v, UUID):
            uuid_obj = v
        elif isinstance(v, str):
            uuid_obj = UUID(v)
        else:
            raise TypeError
        return uuid_obj.hex
    except (AttributeError, ValueError, TypeError):
        raise PydanticCustomError("invalid_uuid_format", "Invalid UUID format")


class Base(BaseModel):
    """Strict base model that rejects unknown request fields."""

    model_config = ConfigDict(extra="forbid", strict=True)


class RaptorConfig(Base):
    """Dataset parser configuration for RAPTOR summary generation."""

    use_raptor: Annotated[bool, Field(default=False)]
    prompt: Annotated[
        str,
        StringConstraints(strip_whitespace=True, min_length=1),
        Field(
            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}"
        ),

View on GitHub (pinned to 554fb1133a)

Solutions

1. Send the full canonical UUID string, e.g. "550e8400-e29b-41d4-a716-446655440000" (hyphenated or 32-char hex both work; hyphens are stripped automatically).
2. Verify the value came from the API's own response (id field) rather than an internal/legacy identifier.
3. Trim whitespace and confirm length is 32 hex chars (plus optional hyphens) before sending.

Example fix

# before
{"document_id": "doc-12345"}

# after
{"document_id": "550e8400e29b41d4a716446655440000"}

import re

def normalize_uuid(value: str) -> str | None:
    """Return 32-hex canonical form, or None if invalid."""
    cleaned = value.strip().replace("-", "")
    return cleaned if re.fullmatch(r"[0-9a-fA-F]{32}", cleaned) else None

if (uid := normalize_uuid(raw_id)) is None:
    raise ClientError(f"not a valid UUID: {raw_id!r}")

function isUuid(v: unknown): v is string {
  return typeof v === "string" && /^[0-9a-fA-F]{32}$/.test(v.replace(/-/g, ""));
}

try:
    model = MyRequest(dataset_id=raw)
except ValidationError as e:
    if any(err["type"] == "invalid_uuid_format" for err in e.errors()):
        log.warning("bad UUID %r — refetch id from the API", raw)

When it happens

Trigger: 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".

Common situations: 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.

Related errors

• Invalid {label} format: {value!r}
• page_size must be less than or equal to {REST_API_MAX_PAGE_S
• {field_name} must contain at most {REST_API_MAX_IDS} IDs
• format_invalid
• duplicate_uuids

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