influxdata/influxdb · error · UploadError

failed to construct IOx parquet metadata

Error message

failed to construct IOx parquet metadata: {0}

What it means

UploadError::Metadata, raised during Parquet metadata conversion when attempting to instantiate a valid IoxParquetMetaData instance fails. The inner crate::metadata::Error is included, covering issues such as missing time-column statistics or wrong time column type in the written file.

Solutions

1. Inspect the wrapped crate::metadata::Error (likely NoColumnStatisticsFound or IncorrectTimeColumnType) and fix the root cause
2. Ensure the writer emits statistics for the time column and writes it as Parquet INT64
3. Re-write the file with corrected writer properties
4. Check for schema drift between the writer and the expected IOx schema

Example fix

// before: writer without statistics, later rejected by metadata conversion
let props = WriterProperties::builder().set_statistics_enabled(Enabled(false)).build();
// after
let props = WriterProperties::builder().set_statistics_enabled(Enabled(true)).build();

// validate before upload: time column stats exist and are Int64
let meta = footer_metadata(&file)?;
ensure_stats_and_int64_time_column(&meta)?;

match res {
    Err(UploadError::Metadata(inner)) => {
        error!(%inner, "IoxParquetMetaData construction failed; fix writer stats/time column type")
    }
    other => other?,
}

When it happens

Trigger: After writing/upload preparation, converting Parquet file metadata into IoxParquetMetaData fails — typically the written file lacks time-column statistics or the time column is not Int64.

Common situations: Writer configuration dropped or corrupted statistics; schema where the timestamp column was written with an unexpected physical type; version drift producing files the reader-side metadata conversion cannot accept.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Could not find time column statistics
• failed to properly configure parquet upload
• invalid IOx metadata
• invalid statistics
• cannot write parquet to a terminal, use `--output

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

Appendix: source

Thrown at core/parquet_file/src/storage.rs:54

    time::{Duration, Instant},
};
use thiserror::Error;
use tracing::*;

/// Errors returned during a Parquet "put" operation, covering [`RecordBatch`]
/// pull from the provided stream, encoding, and finally uploading the bytes to
/// the object store.
///
/// [`RecordBatch`]: arrow::record_batch::RecordBatch
#[derive(Debug, Error)]
pub enum UploadError {
    /// A codec failure during serialisation.
    #[error(transparent)]
    Serialise(#[from] CodecError),

    /// An error during Parquet metadata conversion when attempting to
    /// instantiate a valid [`IoxParquetMetaData`] instance.
    #[error("failed to construct IOx parquet metadata: {0}")]
    Metadata(crate::metadata::Error),

    /// Uploading the Parquet file to object store failed.
    #[error("failed to upload to object storage: {0}")]
    Upload(#[from] object_store::Error),

    /// Error in configuration.
    #[error("failed to properly configure parquet upload: {0}")]
    Config(#[from] DataFusionError),
}

impl From<UploadError> for DataFusionError {
    fn from(value: UploadError) -> Self {
        match value {
            UploadError::Serialise(e) => {
                Self::Context(String::from("serialize"), Box::new(e.into()))
            }
            UploadError::Metadata(e) => Self::External(Box::new(e)),

View on GitHub (pinned to 06200ef96b)