influxdata/influxdb · error · InvalidKeyError

key ' ' cannot contain spaces

Error message

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

What it means

LineBuilder._validate_key rejects tag/field keys containing a space character, because spaces are line-protocol delimiters between the measurement/tags section and fields, and unescaped spaces in keys would produce malformed line protocol. The helper raises InvalidKeyError naming the key and key_type when a space is found.

Solutions

1. Replace spaces in keys with underscores or strip/normalize whitespace before calling the setter.
2. Sanitize dynamic keys: key = key.replace(' ', '_').strip().
3. Fix upstream data sources (CSV headers, config) to emit space-free keys.

Example fix

# before
lb.tag("host name", host)
# after
lb.tag("host_name", host)

def sanitize_key(key: str) -> str:
    return key.strip().replace(" ", "_")

# then: lb.tag(sanitize_key(k), v)

def has_no_spaces(k) -> bool:
    return isinstance(k, str) and " " not in k

try:
    lb.tag(key, value)
except InvalidKeyError:
    lb.tag(key.replace(" ", "_"), value)

When it happens

Trigger: Calling lb.tag("my key", "v") or any field setter with a key containing a space — commonly keys derived from human-readable labels, CSV headers, or user input with whitespace.

Common situations: Using display names ('host name') as tag keys, CSV column headers with spaces, or names produced by concatenation with spaces.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

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

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