influxdata/influxdb · error · InvalidLineError

At least one field is required: {line}

Error message

At least one field is required: {line}

What it means

LineBuilder.build() raises InvalidLineError when the builder has tags but no fields, because line protocol mandates at least one field set per line — a measurement with only tags is not a valid point. The message includes the partial line built so far (measurement + tags) to help identify the culprit. The check runs at serialization time, not when tags are added.

Source

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

        self._timestamp_ns = timestamp_ns
        return self

    def build(self) -> str:
        """Build the line protocol string."""
        # Start with measurement name (escape commas and spaces)
        line = self._escape_measurement(self.measurement)

        # Add tags if present
        if self.tags:
            tags_str = ",".join(
                f"{key}={self._escape_tag_value(value)}"
                for key, value in self.tags.items()
            )
            line += f",{tags_str}"

        # Add fields (required)
        if not self.fields:
            raise InvalidLineError(f"At least one field is required: {line}")

        fields_str = ",".join(
            f"{self._escape_field_key(key)}={value}"
            for key, value in self.fields.items()
        )
        line += f" {fields_str}"

        # Add timestamp if present
        if self._timestamp_ns is not None:
            line += f" {self._timestamp_ns}"

        return line

View on GitHub (pinned to d28e26e048)

Solutions

1. Ensure at least one field is added before build() — restructure so field addition is not skippable
2. Check len(builder.fields) > 0 (or 'if not builder.fields:') before calling build() and skip/log the empty point
3. Re-examine the record that produced no fields; a point with no field values has nothing to store in InfluxDB

Example fix

# before
line = LineBuilder("cpu").tag("host", "a").build()  # InvalidLineError

# after
line = (
    LineBuilder("cpu")
    .tag("host", "a")
    .float64_field("usage_user", 42.0)
    .build()
)

if not builder.fields:
    logger.warning("no fields for measurement %s; skipping point", builder.measurement)
else:
    line = builder.build()

from influxdb3_py_api.line_builder import InvalidLineError

try:
    line = builder.build()
except InvalidLineError as e:
    logger.warning("incomplete line: %s", e)

When it happens

Trigger: LineBuilder('cpu').tag('host', 'a').build() — build() called before any uint64_field/int64_field/float64_field/string_field/bool_field call. Common when field addition is conditional and every branch skipped, or a refactor dropped the field line.

Common situations: Plugins that add fields per input record where some records carry no measurable values; loops that add tags eagerly but defer fields behind an 'if value is not None' that never fires; test code exercising tag-only construction.

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
• Measurement name cannot contain spaces

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