influxdata/influxdb · error · InvalidKeyError

{key_type} key cannot be empty

Error message

{key_type} key cannot be empty

What it means

LineBuilder._validate_key raises InvalidKeyError with '{key_type} key cannot be empty' when tag() or any field method (uint64_field, int64_field, float64_field, string_field, bool_field) is called with an empty-string key. key_type is either 'tag' or 'field', telling you which call site failed. Empty identifiers cannot be represented in line protocol, so the builder rejects them before mutation.

Source

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

class InvalidLineError(InfluxDBError):
    """Raised when a line protocol string is invalid"""

    pass


class LineBuilder:
    def __init__(self, measurement: str):
        if " " in measurement:
            raise InvalidMeasurementError("Measurement name cannot contain spaces")
        self.measurement = measurement
        self.tags: OrderedDict[str, str] = OrderedDict()
        self.fields: OrderedDict[str, str] = OrderedDict()
        self._timestamp_ns: Optional[int] = None

    def _validate_key(self, key: str, key_type: str) -> None:
        """Validate that a key does not contain spaces, commas, or equals signs."""
        if not key:
            raise InvalidKeyError(f"{key_type} key cannot be empty")
        if " " in key:
            raise InvalidKeyError(f"{key_type} key '{key}' cannot contain spaces")
        if "," in key:
            raise InvalidKeyError(f"{key_type} key '{key}' cannot contain commas")
        if "=" in key:
            raise InvalidKeyError(f"{key_type} key '{key}' cannot contain equals signs")

    def _escape_measurement(self, value: str) -> str:
        """Escape characters in measurement names according to line protocol."""
        return value.replace(",", "\\,").replace(" ", "\\ ")

    def _escape_tag_value(self, value: str) -> str:
        """Escape characters in tag values according to line protocol."""
        return (
            value.replace("\\", "\\\\")
            .replace(",", "\\,")
            .replace("=", "\\=")
            .replace(" ", "\\ ")

View on GitHub (pinned to d28e26e048)

Solutions

1. Check the key is a non-empty string before calling tag()/field methods
2. Fix the upstream producer of the key (missing dict key, blank header, failed split)
3. Skip or default the tag/field explicitly when the key would be empty instead of passing '' through

Example fix

# before
builder.tag(col_name, col_value)  # col_name == '' -> InvalidKeyError

# after
if col_name:
    builder.tag(col_name, str(col_value))

def add_tag(builder, key, value):
    if not isinstance(key, str) or not key:
        raise ValueError(f"tag key missing or empty: {key!r}")
    builder.tag(key, str(value))

from influxdb3_py_api.line_builder import InvalidKeyError

try:
    builder.tag(key, value)
except InvalidKeyError as e:
    logger.warning("dropping bad tag: %s", e)

When it happens

Trigger: builder.tag('', 'host1') or builder.string_field('', 'value'). Typically the key expression evaluates to '' — a missing dict entry, a split() on malformed input yielding '', or a blank CSV column header used as a key.

Common situations: Dynamic key generation from data files (blank headers), parsing 'k=v' strings where the left side is missing, optional config keys that were never set but are passed through unconditionally.

Related errors

• {key_type} key '{key}' cannot contain spaces
• {key_type} key '{key}' cannot contain commas
• {key_type} key '{key}' cannot contain equals signs
• At least one field is required: {line}
• Measurement name cannot contain spaces

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