{"record":{"id":"fe7b97b8682d635f","repo":"cocoindex-io/cocoindex","slug":"invalid-qdrant-point-id-raw-r-strings-must-be-u","errorCode":null,"errorMessage":"Invalid Qdrant point ID {raw!r}: strings must be UUIDs. {_POINT_ID_RULE}","messagePattern":"Invalid Qdrant point ID (.+?): strings must be UUIDs\\. (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/qdrant/_target.py","lineNumber":758,"sourceCode":"    Qdrant only accepts unsigned 64-bit integers and UUIDs (any textual\n    form: hyphenated, 32-char hex, or URN); everything else is rejected at\n    upsert time with an opaque transport error, so fail at declare time\n    with an actionable one instead.\n    \"\"\"\n    if isinstance(raw, int):\n        if not 0 <= raw < 1 << 64:\n            raise ValueError(\n                f\"Invalid Qdrant point ID {raw!r}: out of unsigned 64-bit range. \"\n                f\"{_POINT_ID_RULE}\"\n            )\n        return raw\n    if isinstance(raw, uuid.UUID):\n        return str(raw)\n    if isinstance(raw, str):\n        try:\n            uuid.UUID(raw)\n        except ValueError:\n            raise ValueError(\n                f\"Invalid Qdrant point ID {raw!r}: strings must be UUIDs. \"\n                f\"{_POINT_ID_RULE}\"\n            ) from None\n        return raw\n    raise ValueError(\n        f\"Invalid Qdrant point ID of type {type(raw).__name__}. {_POINT_ID_RULE}\"\n    )\n\n\n__all__ = [\n    \"CollectionSchema\",\n    \"CollectionTarget\",\n    \"PointStruct\",\n    \"QdrantSparseVectorDef\",\n    \"QdrantVectorDef\",\n    \"collection_target\",\n    \"create_client\",\n    \"declare_collection_target\",","sourceCodeStart":740,"sourceCodeEnd":776,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/qdrant/_target.py#L740-L776","documentation":"Qdrant accepts string point IDs only when they are valid UUIDs. declare_point attempts uuid.UUID(raw) on every string ID and raises this ValueError (with the point-ID rule text) for anything that is not a UUID in a form Python's uuid can parse. This fails at declare time rather than with an opaque Qdrant transport error at upsert.","triggerScenarios":"Calling declare_point with a string point ID like \"doc-123\", \"my/file.md\", a numeric string \"42\", or any non-UUID string; also UUID-ish strings with invalid formatting (wrong length/characters).","commonSituations":"Passing file paths or natural keys directly as point IDs; storing integer IDs as strings; truncated or malformed UUIDs copied from logs.","solutions":["Convert the key to a UUID: str(uuid.uuid5(uuid.NAMESPACE_URL, f\"doc/{key}\")) for a stable, deterministic ID.","If you have a numeric ID, pass it as a Python int (in [0, 2^64)) instead of a string.","Validate with `str(uuid.UUID(s))` before declaring if the string is supposed to be a UUID.","Prepend the accepted prefix (urn:uuid: or braces) is fine only if the rest is a valid UUID — otherwise regenerate."],"exampleFix":"// before\nawait target.declare_point(id=\"doc-123\", ...)\n// after\nimport uuid\nawait target.declare_point(id=str(uuid.uuid5(uuid.NAMESPACE_URL, \"doc/doc-123\")), ...)","handlingStrategy":"validation","validationCode":"import uuid\ndef _ensure_uuid_str(s):\n    uuid.UUID(s)  # raises if not a UUID\n    return s","typeGuard":"def is_uuid_string(s):\n    if not isinstance(s, str): return False\n    try: uuid.UUID(s); return True\n    except ValueError: return False","tryCatchPattern":"try:\n    await target.declare_point(id=pid, ...)\nexcept ValueError as e:\n    pid = str(uuid.uuid5(uuid.NAMESPACE_URL, f\"doc/{raw_key}\"))\n    await target.declare_point(id=pid, ...)","preventionTips":["Derive point IDs from natural keys via uuid.uuid5 instead of using raw strings.","Pass numeric IDs as ints, not strings.","Add an is_uuid_string check in your declare wrapper."],"tags":["qdrant","point-id","uuid"],"backgroundTag":"invalid-argument-format","analyzedSha":"e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b","analyzedAt":"2026-09-08T15:59:19.997Z","contentChangedAt":"2026-09-08T15:59:19.997Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}