influxdata/influxdb · error · InvalidKeyError

{key_type} key '{key}' cannot contain commas

Error message

{key_type} key '{key}' cannot contain commas

What it means

LineBuilder._validate_key raises InvalidKeyError when a tag or field key contains a comma. Commas separate the measurement from tag pairs and tag pairs from each other in line protocol, so a comma in an identifier would split the element; the builder rejects it. Note this applies to keys only — tag values are auto-escaped, and keys are deliberately not escaped for you.

Source

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

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."""

View on GitHub (pinned to d28e26e048)

Solutions

1. Use a different separator when composing key names (underscore or dash)
2. If you meant to store a comma-separated list, put it in the tag VALUE (auto-escaped) or a string field, not the key
3. Add a key sanitizer that strips/replaces ',', ' ', '=' in one pass

Example fix

# before
builder.tag(",".join(["region", "zone"]), "us")  # InvalidKeyError

# after
builder.tag("region_zone", "us")  # or store the list as a value:
builder.tag("location", ",".join(["region", "zone"]))  # value is escaped

def normalize_key(k: str) -> str:
    return k.replace(",", "_").replace(" ", "_").replace("=", "_")

builder.tag(normalize_key(raw_key), value)

from influxdb3_py_api.line_builder import InvalidKeyError

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

When it happens

Trigger: builder.tag('region,zone', 'us') or builder.string_field('a,b', 'x') — often caused by mistakenly using a joined string (','.join([...])) as a key instead of as a value, or embedding list output into a key name.

Common situations: Composing composite keys by joining values with commas; keys built from f-strings over lists ('tags={my_list}'); data copied from CSV where a column name contains a comma.

Related errors

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