influxdata/influxdb · error · Error::Io

io error

Error message

io error: {0}

What it means

The Io variant of influxdb3_commands::query::Error, converted via #[from] from std::io::Error. It wraps I/O failures in the query command, most notably failures writing the query output (parquet file creation/write, stdout pipe) or reading input files/stdin. The underlying std::io::Error is preserved as the source.

Solutions

1. Check the error source (std::io::Error kind) to identify the exact I/O failure.
2. Verify the --output directory exists and is writable, or create it first.
3. Ensure sufficient disk space/quota for the parquet output size.
4. Fix pipe consumers (e.g. use `head -c` tolerant patterns) or redirect to a file instead; check file/stdin permissions.
5. Run with appropriate user permissions or adjust container volume mounts.

Example fix

// before
influxdb3 query --output /nonexistent-dir/results.parquet "SELECT * FROM cpu"
// after
mkdir -p ./results && influxdb3 query --output ./results/results.parquet "SELECT * FROM cpu"

// before requesting parquet output, ensure the destination is writable
fn ensure_output_writable(path: &std::path::Path) -> std::io::Result<()> {
    if let Some(dir) = path.parent() { std::fs::create_dir_all(dir)?; }
    let f = std::fs::OpenOptions::new().create(true).append(true).open(path)?;
    Ok(())
}

fn is_io_error(e: &influxdb3_commands::query::Error) -> bool {
    matches!(e, influxdb3_commands::query::Error::Io(_))
}

match run_query_with_output(path).await {
    Err(influxdb3_commands::query::Error::Io(io)) if io.kind() == std::io::ErrorKind::BrokenPipe => {
        // downstream consumer closed stdout; degrade gracefully
    }
    Err(e) => return Err(e.into()),
    Ok(v) => v,
}

When it happens

Trigger: Running `influxdb3 query --output file.parquet` where the file cannot be created or written (bad path, missing directory, permissions, disk full); reading query input from a file/stdin that fails; broken pipe when stdout is closed by the consumer (e.g. piping into `head`).

Common situations: --output path in a non-existent or read-only directory; disk quota exceeded while writing large parquet results; piping output to a short-lived consumer that exits early (broken pipe); insufficient permissions under restricted users/containers; stdin redirection mistakes.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• error writing wal file
• IO error
• tempfile i/o
• is not a valid data type, values are int64, uint64…
• Cannot parse object store config

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

Appendix: source

Thrown at influxdb3_commands/src/query.rs:25

use tokio::{
    fs::OpenOptions,
    io::{self, AsyncWriteExt},
};
use url::Url;

use crate::common::Format;

use super::common::InfluxDb3Config;

#[derive(Debug, thiserror::Error)]
pub enum Error {
    #[error(transparent)]
    Client(#[from] influxdb3_client::Error),

    #[error("invlid UTF8 received from server: {0}")]
    Utf8(#[from] Utf8Error),

    #[error("io error: {0}")]
    Io(#[from] io::Error),

    #[error("cannot write parquet to a terminal, use `--output <file>` or pipe the output")]
    NoOutputFileForParquet,
    #[error(
        "No input from stdin detected, no string was passed in,  and no file \
        path was given"
    )]
    NoInput,
}

pub type Result<T> = std::result::Result<T, Error>;

#[derive(Debug, Parser)]
#[clap(visible_alias = "q")]
pub struct Config {
    /// Common InfluxDB 3 server config
    #[clap(flatten)]

View on GitHub (pinned to 06200ef96b)