cocoindex-io/cocoindex · error · ValueError

Invalid Qdrant point ID {raw!r}: out of unsigned 64-bit rang

Error message

Invalid Qdrant point ID {raw!r}: out of unsigned 64-bit range. Qdrant point IDs must be an unsigned 64-bit integer or a UUID (str or uuid.UUID); see https://qdrant.tech/documentation/manage-data/points/#point-ids. For a stable ID derived from an arbitrary string key, use uuid.uuid5, e.g. str(uuid.uuid5(uuid.NAMESPACE_URL, f"doc/{key}")).

What it means

Qdrant point IDs must be either an unsigned 64-bit integer or a UUID. When declaring a point, declare_point validates the ID: if it is an int outside [0, 2^64), this ValueError is raised with the full rule text, including a uuid.uuid5 recipe for deriving a stable ID from arbitrary string keys. This fails fast instead of hitting an opaque Qdrant transport error at upsert time.

Source

Thrown at python/cocoindex/connectors/qdrant/_target.py:747

    "Qdrant point IDs must be an unsigned 64-bit integer or a UUID "
    "(str or uuid.UUID); see "
    "https://qdrant.tech/documentation/manage-data/points/#point-ids. For a "
    "stable ID derived from an arbitrary string key, use uuid.uuid5, e.g. "
    'str(uuid.uuid5(uuid.NAMESPACE_URL, f"doc/{key}")).'
)


def _validate_point_id(raw: object) -> _PointId:
    """Validate a point ID against Qdrant's server-side rules, eagerly.

    Qdrant only accepts unsigned 64-bit integers and UUIDs (any textual
    form: hyphenated, 32-char hex, or URN); everything else is rejected at
    upsert time with an opaque transport error, so fail at declare time
    with an actionable one instead.
    """
    if isinstance(raw, int):
        if not 0 <= raw < 1 << 64:
            raise ValueError(
                f"Invalid Qdrant point ID {raw!r}: out of unsigned 64-bit range. "
                f"{_POINT_ID_RULE}"
            )
        return raw
    if isinstance(raw, uuid.UUID):
        return str(raw)
    if isinstance(raw, str):
        try:
            uuid.UUID(raw)
        except ValueError:
            raise ValueError(
                f"Invalid Qdrant point ID {raw!r}: strings must be UUIDs. "
                f"{_POINT_ID_RULE}"
            ) from None
        return raw
    raise ValueError(
        f"Invalid Qdrant point ID of type {type(raw).__name__}. {_POINT_ID_RULE}"
    )

View on GitHub (pinned to e84aa99b32)

Solutions

1. Mask a hashed key into unsigned 64-bit range: pid = hash(key) % (1 << 64).
2. Prefer a UUID derived via uuid.uuid5, e.g. str(uuid.uuid5(uuid.NAMESPACE_URL, f"doc/{key}")) — stable and always valid.
3. If the ID comes from another system, verify it fits in [0, 2^64) before declaring the point.

Example fix

// before
point_id = hash(doc_key)  # may be negative
// after
import uuid
point_id = str(uuid.uuid5(uuid.NAMESPACE_URL, f"doc/{doc_key}"))

def _ensure_point_id(raw):
    if isinstance(raw, int) and not 0 <= raw < (1 << 64):
        raise ValueError(f"point id {raw} out of u64 range")
    return raw

lambda raw: isinstance(raw, int) and not isinstance(raw, bool) and 0 <= raw < (1 << 64)

try:
    await target.declare_point(id=pid, ...)
except ValueError as e:
    log.error("bad point id: %s", e)
    raise

When it happens

Trigger: Calling declare_point with an int point ID that is negative or >= 2^64 (18446744073709551616), e.g. hash() output (which can be negative), a Snowflake-style large ID, or a Python int parsed from a big numeric key.

Common situations: Using Python's built-in hash() as an ID (signed, 64-bit but can be negative); using database auto-increment or snowflake IDs exceeding 2^64; hashing a string key and not masking to unsigned 64-bit.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Invalid vector definition: {vectors}
• Qdrant {kind} name must not be empty
• Invalid Qdrant point ID {raw!r}: strings must be UUIDs. {_PO
• Invalid Qdrant point ID of type {type(raw).__name__}. {_POIN
• expected None{loc}, got {type(value).__name__}

AI-assisted analysis of cocoindex-io/cocoindex@e84aa99b32 (2026-09-08). Data as JSON: /api/errors/7745531d42ffcaad. Report an issue: GitHub.