What causes "Invalid Qdrant point ID of type {type(raw).__name__}. {_POINT_ID_RULE}" in cocoindex-io/cocoindex?

Extract the actual ID value before declaring: use the str key or int ID, not the containing object.

cocoindex-io/cocoindex · error · ValueError

Invalid Qdrant point ID of type {type(raw).name}. {_POIN

Error message

Invalid Qdrant point ID of type {type(raw).__name__}. {_POINT_ID_RULE}

What it means

After checking int and UUID/str cases, _validate_point_id rejects any other type with this ValueError naming the offending type, plus the point-ID rule. Qdrant only supports unsigned 64-bit ints and UUIDs (str or uuid.UUID) as point IDs, so bytes, lists, dicts, None, etc. are rejected at declare time.

Source

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

    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}"
    )


__all__ = [
    "CollectionSchema",
    "CollectionTarget",
    "PointStruct",
    "QdrantSparseVectorDef",
    "QdrantVectorDef",
    "collection_target",
    "create_client",
    "declare_collection_target",
    "mount_collection_target",
]

View on GitHub (pinned to e84aa99b32)

Solutions

Extract the actual ID value before declaring: use the str key or int ID, not the containing object.
For bytes from a hash, convert: str(uuid.UUID(bytes= digest)) or format as a UUID string.
Replace None with a real ID — generate one via uuid.uuid4()/uuid5.
Add an isinstance check (int | str | uuid.UUID) before calling declare_point.

Example fix

// before
await target.declare_point(id=some_file_like, ...)
// after
await target.declare_point(id=str(uuid.uuid5(uuid.NAMESPACE_URL, some_file_like.file_path.path.as_posix())), ...)

Defensive patterns

Strategy: type-guard

Validate before calling

def _valid_point_id(raw):
    import uuid
    return (isinstance(raw, int) and 0 <= raw < (1 << 64)) or is_uuid_string(raw) or isinstance(raw, uuid.UUID)

Type guard

def is_valid_point_id(raw) -> bool:
    import uuid
    if isinstance(raw, uuid.UUID): return True
    if isinstance(raw, str):
        try: uuid.UUID(raw); return True
        except ValueError: return False
    return isinstance(raw, int) and 0 <= raw < (1 << 64)

Try / catch

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

Prevention

Unwrap objects before declaring — pass the ID string/int, not the containing object.
Ensure optional ID fields have real defaults, not None.
Centralize point-ID creation in one helper that always returns int|str|UUID.

When it happens

Trigger: Calling declare_point with id=None, bytes, a tuple, a list, or any non-int/str/UUID object; commonly from passing a dictionary key object or forgetting to extract the string/ID field from a wrapper.

Common situations: Passing a FileLike/key object instead of its ID string; None from an optional field defaulting to None; bytes from a hash function.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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