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.

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

• At least one of dest_file_id or new_name must be provided
• duplicate_uuids
• must contain at most IDs
• format_invalid
• Invalid format

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

Appendix: 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)