influxdata/influxdb · error · InvalidKeyError

{key_type} key '{key}' cannot contain spaces

Error message

{key_type} key '{key}' cannot contain spaces

What it means

LineBuilder._validate_key raises InvalidKeyError when a tag or field key contains a space. Spaces are structural separators in line protocol (measurement,tags<space>fields<space>timestamp), so a raw space inside an identifier would shift the parse; the builder rejects it rather than silently escaping keys. Tag and field keys must be space-free.

Source

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

    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. Rename the key: replace spaces with underscores (snake_case) at ingest
2. Sanitize all dynamic keys with a single normalize function before feeding the builder
3. If renaming is impossible, log and skip the offending tag/field rather than letting the whole build fail

Example fix

# before
builder.tag("server name", "host1")  # InvalidKeyError

# after
builder.tag("server_name", "host1")

def valid_lp_key(k: str) -> bool:
    return bool(k) and not any(c in k for c in " ,=")

if valid_lp_key(tag_key):
    builder.tag(tag_key, tag_value)

from influxdb3_py_api.line_builder import InvalidKeyError

try:
    builder.tag(tag_key, tag_value)
except InvalidKeyError as e:
    logger.warning("renaming/skipping key: %s", e)

When it happens

Trigger: builder.tag('server name', 'host1') or builder.float64_field('mem used', 0.64) — any tag()/field call whose key contains ' '. The offending key is echoed in the message.

Common situations: Keys derived from human-readable labels ('cpu usage'), CSV/JSON property names with spaces, or template strings where a variable expanded with surrounding whitespace ('{name} ')

Related errors

• {key_type} key cannot be empty
• {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/8d8e122418c83885. Report an issue: GitHub.