influxdata/influxdb · error · Error

Missing InfluxQL metadata

Error message

Missing InfluxQL metadata

What it means

Error::MissingMetadata is thrown when the Arrow schema of a query result does not contain the InfluxQlMetadata key in its metadata map. The InfluxQL formatter relies on this metadata to know measurement names, tag keys, and field keys so it can render results as line protocol; without it, formatting cannot proceed.

Solutions

1. Ensure the query is sent to the InfluxQL query endpoint so the server annotates the Arrow schema with InfluxQlMetadata
2. Check the returned schema metadata keys (batch.schema().metadata()) to confirm the InfluxQlMetadata entry is present
3. If constructing batches in tests, serialize an InfluxQlMetadata as JSON and insert it under the expected metadata key before formatting
4. Upgrade the InfluxDB IOx server/client pair so both agree on the metadata convention

Example fix

// before
let batches = client.query_sql("SELECT * FROM cpu").await?;
let out = influxql_formatter.format(&batches)?; // MissingMetadata
// after
let batches = client.query_influxql("SELECT * FROM cpu").await?;
assert!(batches[0].schema().metadata().contains_key("iox::influxql::v1"));
let out = influxql_formatter.format(&batches)?;

const IOX_INFLUXQL_KEY: &str = "iox::influxql::v1";
fn has_influxql_metadata(batches: &[RecordBatch]) -> bool {
    batches.first()
        .map(|b| b.schema().metadata().contains_key(IOX_INFLUXQL_KEY))
        .unwrap_or(false)
}

fn is_missing_metadata(e: &influxql_format::Error) -> bool {
    matches!(e, influxql_format::Error::MissingMetadata)
}

When it happens

Trigger: Calling format::influxql::Formatter::format (or new) on RecordBatches whose SchemaRef.metadata lacks the InfluxQlMetadata key — typically batches obtained from a non-InfluxQL endpoint, from the flight/sql path, or hand-constructed batches.

Common situations: Pointing the client at a server that does not annotate InfluxQL results (wrong endpoint, e.g., SQL query API instead of the InfluxQL query API); constructing test batches manually without inserting the metadata; using an older IOx server that predates the metadata annotation.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Invalid InfluxQL metadata
• Arrow error
• Unsupported InfluxQL data type
• Arrow csv printing error
• arrow error

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

Appendix: source

Thrown at core/influxdb_iox_client/src/format/influxql.rs:20

use arrow::datatypes::DataType;
use arrow::error::ArrowError;
use arrow::record_batch::RecordBatch;
use arrow::util::display::ArrayFormatter;
use comfy_table::{Cell, Table};
use generated_types::influxdata::iox::querier::v1::InfluxQlMetadata;
use std::io::Write;
use std::iter;
use thiserror::Error;

/// Error type for results formatting
#[derive(Debug, Error)]
pub enum Error {
    /// Arrow error.
    #[error("Arrow error: {}", .0)]
    Arrow(ArrowError),

    /// [`InfluxQlMetadata`] not found in Arrow schema metadata.
    #[error("Missing InfluxQL metadata")]
    MissingMetadata,

    /// Error deserializing [`InfluxQlMetadata`] from Arrow schema metadata.
    #[error("Invalid InfluxQL metadata: {0}")]
    InvalidMetadata(#[from] serde_json::Error),

    /// Error writing formatted output.
    #[error("Error writing output: {0}")]
    Write(#[from] std::io::Error),
}
type Result<T, E = Error> = std::result::Result<T, E>;

/// Options for controlling how table borders are rendered.
#[derive(Debug, Default, Clone, Copy)]
pub enum TableBorders {
    /// Use ASCII characters.
    #[default]
    Ascii,

View on GitHub (pinned to 06200ef96b)