influxdata/influxdb · error · InvalidKeyError

key ' ' cannot contain equals signs

Error message

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

What it means

The LineBuilder validates tag keys and field keys against line protocol restrictions before use. InfluxDB line protocol uses '=' to delimit key from value, so '=' in a key would corrupt the written line; this error rejects any tag or field key containing '='. Unlike spaces and commas, '=' in keys is not escapable in this builder, so it must be removed outright.

Solutions

1. Remove or replace '=' in the key before passing it to the builder, e.g. key.replace('=', ':') or key.split('=')[0].
2. If the '=' is semantically meaningful, move it into the tag VALUE or a field value, which are escaped by the builder.
3. Sanitize dynamic keys (headers, query params) at the ingestion boundary so '=' never reaches tag()/field calls.

Example fix

// before
builder.tag("region=us-east", "primary")
// after
builder.tag("region:us-east", "primary")  # or builder.tag("region", "us-east")

def valid_key(key: str) -> bool:
    return bool(key) and not any(c in key for c in ' ,=')

try:
    builder.tag(key, value)
except InvalidKeyError:
    key = key.replace('=', ':')
    builder.tag(key, value)

When it happens

Trigger: Calling tag(), uint64_field(), int64_field(), float64_field(), string_field(), or bool_field() with a key containing an equals sign, e.g. builder.tag("a=b", "v") or builder.string_field("status=ok", "x").

Common situations: Building keys dynamically from HTTP headers, query strings, URL fragments, or label strings like 'key=value' copied from config files; parsing CSV headers that contain '='; joining name and unit with '=' (e.g. 'temp=C').

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• At least one field is required
• key cannot be empty
• key ' ' cannot contain commas
• key ' ' cannot contain spaces
• Measurement name cannot contain spaces

AI-assisted analysis of influxdata/influxdb@06200ef96b (2026-09-19). Data as JSON: /api/errors/79f69ae8c74fb579. Report an issue: GitHub.

Appendix: 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 06200ef96b)