{"record":{"id":"7745531d42ffcaad","repo":"cocoindex-io/cocoindex","slug":"invalid-qdrant-point-id-raw-r-out-of-unsigned-6","errorCode":null,"errorMessage":"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}\")).","messagePattern":"Invalid Qdrant point ID (.+?): 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/(.+?)\"\\)\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/qdrant/_target.py","lineNumber":747,"sourceCode":"    \"Qdrant point IDs must be an unsigned 64-bit integer or a UUID \"\n    \"(str or uuid.UUID); see \"\n    \"https://qdrant.tech/documentation/manage-data/points/#point-ids. For a \"\n    \"stable ID derived from an arbitrary string key, use uuid.uuid5, e.g. \"\n    'str(uuid.uuid5(uuid.NAMESPACE_URL, f\"doc/{key}\")).'\n)\n\n\ndef _validate_point_id(raw: object) -> _PointId:\n    \"\"\"Validate a point ID against Qdrant's server-side rules, eagerly.\n\n    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    )","sourceCodeStart":729,"sourceCodeEnd":765,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/qdrant/_target.py#L729-L765","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Mask a hashed key into unsigned 64-bit range: pid = hash(key) % (1 << 64).","Prefer a UUID derived via uuid.uuid5, e.g. str(uuid.uuid5(uuid.NAMESPACE_URL, f\"doc/{key}\")) — stable and always valid.","If the ID comes from another system, verify it fits in [0, 2^64) before declaring the point."],"exampleFix":"// before\npoint_id = hash(doc_key)  # may be negative\n// after\nimport uuid\npoint_id = str(uuid.uuid5(uuid.NAMESPACE_URL, f\"doc/{doc_key}\"))","handlingStrategy":"validation","validationCode":"def _ensure_point_id(raw):\n    if isinstance(raw, int) and not 0 <= raw < (1 << 64):\n        raise ValueError(f\"point id {raw} out of u64 range\")\n    return raw","typeGuard":"lambda raw: isinstance(raw, int) and not isinstance(raw, bool) and 0 <= raw < (1 << 64)","tryCatchPattern":"try:\n    await target.declare_point(id=pid, ...)\nexcept ValueError as e:\n    log.error(\"bad point id: %s\", e)\n    raise","preventionTips":["Never use Python hash() directly as a point ID; mask with % (1 << 64) or use uuid5.","Prefer str(uuid.uuid5(uuid.NAMESPACE_URL, key)) for arbitrary string keys.","Validate ID range at the boundary where IDs are generated."],"tags":["qdrant","point-id","validation"],"backgroundTag":"value-out-of-range","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"}