influxdata/influxdb · error · ValueError

uint64 field '{key}' cannot be negative

Error message

uint64 field '{key}' cannot be negative

What it means

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.

Source

Thrown at influxdb3_py_api/src/line_builder/line_builder.py:81

        """Escape characters in field keys according to line protocol."""
        return (
            value.replace("\\", "\\\\")
            .replace(",", "\\,")
            .replace("=", "\\=")
            .replace(" ", "\\ ")
        )

    def tag(self, key: str, value: str) -> "LineBuilder":
        """Add a tag to the line protocol."""
        self._validate_key(key, "tag")
        self.tags[key] = str(value)
        return self

    def uint64_field(self, key: str, value: int) -> "LineBuilder":
        """Add an unsigned integer field to the line protocol."""
        self._validate_key(key, "field")
        if value < 0:
            raise ValueError(f"uint64 field '{key}' cannot be negative")
        self.fields[key] = f"{value}u"
        return self

    def int64_field(self, key: str, value: int) -> "LineBuilder":
        """Add an integer field to the line protocol."""
        self._validate_key(key, "field")
        self.fields[key] = f"{value}i"
        return self

    def float64_field(self, key: str, value: float) -> "LineBuilder":
        """Add a float field to the line protocol."""
        self._validate_key(key, "field")
        # Check if value has no decimal component
        self.fields[key] = f"{int(value)}.0" if value % 1 == 0 else str(value)
        return self

    def string_field(self, key: str, value: str) -> "LineBuilder":
        """Add a string field to the line protocol."""

View on GitHub (pinned to d28e26e048)

Solutions

1. If the field can be negative, declare and write it as int64_field() consistently
2. Validate value >= 0 before calling uint64_field and skip/clamp per your data policy
3. Fix the upstream calculation if negatives are unexpected (e.g. counter-reset handling)

Example fix

# before
builder.uint64_field("delta", new_count - old_count)  # negative -> ValueError

# after
builder.int64_field("delta", new_count - old_count)  # signed field holds negatives

# decide field type by semantic: signed columns always use int64_field
if field_semantics[name] == "signed":
    builder.int64_field(name, value)
else:
    if value < 0:
        raise ValueError(f"{name} unexpectedly negative: {value}")
    builder.uint64_field(name, value)

try:
    builder.uint64_field(name, value)
except ValueError as e:
    logger.warning("falling back to signed field for %s: %s", name, e)
    builder.int64_field(name, value)

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Measurement name cannot contain spaces
• {key_type} key cannot be empty
• {key_type} key '{key}' cannot contain spaces
• {key_type} key '{key}' cannot contain commas
• {key_type} key '{key}' cannot contain equals signs

AI-assisted analysis of influxdata/influxdb@d28e26e048 (2026-08-16). Data as JSON: /api/errors/790c985d2ac2ef3f. Report an issue: GitHub.