{"record":{"id":"790c985d2ac2ef3f","repo":"influxdata/influxdb","slug":"uint64-field-key-cannot-be-negative","errorCode":null,"errorMessage":"uint64 field '{key}' cannot be negative","messagePattern":"uint64 field '(.+?)' cannot be negative","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"influxdb3_py_api/src/line_builder/line_builder.py","lineNumber":81,"sourceCode":"        \"\"\"Escape characters in field keys according to line protocol.\"\"\"\n        return (\n            value.replace(\"\\\\\", \"\\\\\\\\\")\n            .replace(\",\", \"\\\\,\")\n            .replace(\"=\", \"\\\\=\")\n            .replace(\" \", \"\\\\ \")\n        )\n\n    def tag(self, key: str, value: str) -> \"LineBuilder\":\n        \"\"\"Add a tag to the line protocol.\"\"\"\n        self._validate_key(key, \"tag\")\n        self.tags[key] = str(value)\n        return self\n\n    def uint64_field(self, key: str, value: int) -> \"LineBuilder\":\n        \"\"\"Add an unsigned integer field to the line protocol.\"\"\"\n        self._validate_key(key, \"field\")\n        if value < 0:\n            raise ValueError(f\"uint64 field '{key}' cannot be negative\")\n        self.fields[key] = f\"{value}u\"\n        return self\n\n    def int64_field(self, key: str, value: int) -> \"LineBuilder\":\n        \"\"\"Add an integer field to the line protocol.\"\"\"\n        self._validate_key(key, \"field\")\n        self.fields[key] = f\"{value}i\"\n        return self\n\n    def float64_field(self, key: str, value: float) -> \"LineBuilder\":\n        \"\"\"Add a float field to the line protocol.\"\"\"\n        self._validate_key(key, \"field\")\n        # Check if value has no decimal component\n        self.fields[key] = f\"{int(value)}.0\" if value % 1 == 0 else str(value)\n        return self\n\n    def string_field(self, key: str, value: str) -> \"LineBuilder\":\n        \"\"\"Add a string field to the line protocol.\"\"\"","sourceCodeStart":63,"sourceCodeEnd":99,"githubUrl":"https://github.com/influxdata/influxdb/blob/d28e26e048401c53cbb98cf2d6ab0cf1e98048ca/influxdb3_py_api/src/line_builder/line_builder.py#L63-L99","documentation":"uint64_field() formats the value with a 'u' suffix, the line protocol marker for unsigned 64-bit integers. Unsigned integers cannot be negative by definition, so a value < 0 raises a plain ValueError before the field is stored. Use int64_field() (suffix 'i') for values that can legitimately be negative.","triggerScenarios":"builder.uint64_field('count', -5). Typical when deltas, deltas of counters, or arithmetic on user data produce a negative, or when a uint-typed column read from another DB wraps around.","commonSituations":"Counter decreases (reset after restart), rate/delta calculations that dip below zero, signed values fed into a field defined as uint64 in the table schema, porting data from systems with different integer semantics.","solutions":["If the field can be negative, declare and write it as int64_field() consistently","Validate value >= 0 before calling uint64_field and skip/clamp per your data policy","Fix the upstream calculation if negatives are unexpected (e.g. counter-reset handling)"],"exampleFix":"# before\nbuilder.uint64_field(\"delta\", new_count - old_count)  # negative -> ValueError\n\n# after\nbuilder.int64_field(\"delta\", new_count - old_count)  # signed field holds negatives","handlingStrategy":"validation","validationCode":"# decide field type by semantic: signed columns always use int64_field\nif field_semantics[name] == \"signed\":\n    builder.int64_field(name, value)\nelse:\n    if value < 0:\n        raise ValueError(f\"{name} unexpectedly negative: {value}\")\n    builder.uint64_field(name, value)","typeGuard":null,"tryCatchPattern":"try:\n    builder.uint64_field(name, value)\nexcept ValueError as e:\n    logger.warning(\"falling back to signed field for %s: %s\", name, e)\n    builder.int64_field(name, value)","preventionTips":["Pick the field type from the data's domain (can it be negative?) once, at schema-design time","Clamp or flag negative deltas before writing unsigned counters","Keep a single mapping of field name -> intended line protocol type"],"tags":["influxdb","line-protocol","python","uint64","field-types","validation"],"backgroundTag":"unsigned-type-negative-value","analyzedSha":"d28e26e048401c53cbb98cf2d6ab0cf1e98048ca","analyzedAt":"2026-08-16T19:53:34.623Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}