influxdata/influxdb · error · InvalidKeyError

{key_type} key '{key}' cannot contain equals signs

Error message

{key_type} key '{key}' cannot contain equals signs

What it means

LineBuilder._validate_key raises InvalidKeyError when a tag or field key contains an equals sign. '=' separates keys from values in line protocol tag/field pairs, so an '=' inside an identifier makes parsing ambiguous; the builder rejects it. Tag values and field values containing '=' are fine because they are escaped automatically.

Source

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

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(" ", "\\ ")
        )

    def _escape_field_key(self, value: str) -> str:
        """Escape characters in field keys according to line protocol."""
        return (
            value.replace("\\", "\\\\")

View on GitHub (pinned to d28e26e048)

Solutions

1. Split the token on the first '=' and use only the left side as the key
2. Fix the f-string that embeds '=' into a key name
3. Run keys through a sanitizer that strips ' ', ',', '=' before the builder call

Example fix

# before
builder.tag(raw_token, "x")  # raw_token == 'a=b' -> InvalidKeyError

# after
key, _, value = raw_token.partition("=")
builder.tag(key, value or "x")

def split_kv(token: str) -> tuple[str, str]:
    key, sep, value = token.partition("=")
    if not sep or not key:
        raise ValueError(f"expected key=value, got {token!r}")
    return key, value

from influxdb3_py_api.line_builder import InvalidKeyError

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

When it happens

Trigger: builder.tag('a=b', 'x') — most often the caller parsed a 'key=value' string but passed the whole unsplit token as the key, or an f-string key accidentally includes '=' (e.g. f'{k}={v}').

Common situations: Handling 'k=v' config/metric strings from env files, log lines, or query strings where split('=') was skipped or applied to the wrong variable.

Related errors

• {key_type} key cannot be empty
• {key_type} key '{key}' cannot contain spaces
• {key_type} key '{key}' cannot contain commas
• 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/79f69ae8c74fb579. Report an issue: GitHub.