influxdata/influxdb · error · InvalidMeasurementError

Measurement name cannot contain spaces

Error message

Measurement name cannot contain spaces

What it means

LineBuilder.__init__ in the influxdb3_py_api Python package (the API used by InfluxDB 3 processing-engine plugins to build line protocol) rejects any measurement name containing a space. In line protocol a space separates the measurement+tag set from the field set, so an unescaped space makes the line ambiguous; the constructor fails fast with InvalidMeasurementError instead of emitting a corrupt line. Although build() later escapes commas and spaces via _escape_measurement, the constructor still rejects spaces upfront.

Source

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

    pass


class InvalidKeyError(InfluxDBError):
    """Raised when a tag or field key is invalid"""

    pass


class InvalidLineError(InfluxDBError):
    """Raised when a line protocol string is invalid"""

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

View on GitHub (pinned to d28e26e048)

Solutions

1. Replace spaces in the measurement name with underscores or dashes before constructing LineBuilder
2. If the space is only leading/trailing whitespace, apply name.strip() first
3. For truly arbitrary names, sanitize at your ingest boundary (whitelist/replace) so builder input is always clean
4. Wrap construction in try/except InvalidMeasurementError and log the offending name when ingesting external data

Example fix

# before
builder = LineBuilder("cpu usage")  # InvalidMeasurementError

# after
builder = LineBuilder("cpu_usage")

def safe_measurement(name: str) -> str:
    cleaned = name.strip().replace(" ", "_")
    if not cleaned:
        raise ValueError("measurement name is empty")
    return cleaned

builder = LineBuilder(safe_measurement(raw_name))

from influxdb3_py_api.line_builder import LineBuilder, InfluxDBError

try:
    builder = LineBuilder(raw_name)
except InfluxDBError as e:
    logger.warning("skipping invalid measurement %r: %s", raw_name, e)
    return

When it happens

Trigger: Calling LineBuilder('cpu usage') or LineBuilder('my measurement') in Python plugin code, e.g. when constructing lines for context.write_db_lines() or a LogWriter. Any measurement string containing at least one space character raises immediately, before any tag or field can be added.

Common situations: Measurement names taken from user input, CSV headers, metric names imported from other monitoring systems (e.g. 'disk used percent'), or copy-pasted strings with stray whitespace. Plugins that build measurement names dynamically from unvalidated third-party data.

Related errors

• {key_type} key cannot be empty
• {key_type} key '{key}' cannot contain spaces
• {key_type} key '{key}' cannot contain commas
• {key_type} key '{key}' cannot contain equals signs
• uint64 field '{key}' cannot be negative

AI-assisted analysis of influxdata/influxdb@d28e26e048 (2026-08-16). Data as JSON: /api/errors/753d7a18b1a3bcce. Report an issue: GitHub.