influxdata/influxdb · error · Error::Utf8

Invalid UTF8

Error message

Invalid UTF8: {message} {error}

What it means

`Error::Utf8 { message, error }` indicates a request payload was not valid UTF-8. The v1 API requires text-based bodies/parameters; decoding a byte payload as UTF-8 fails and the error carries both a static context `message` and the underlying `error` string.

Solutions

1. Re-encode the payload as UTF-8 before sending (e.g. `iconv -f ISO-8859-1 -t UTF-8`).
2. Ensure files are text, not binary; do not send compressed bytes unless the API expects them.
3. Use `String::from_utf8` client-side to validate payloads before transmission.

Example fix

// before
let body = legacy_latin1_bytes; // invalid UTF-8
// after
let body = String::from_utf8(legacy_latin1_bytes).expect("payload must be utf-8");

fn ensure_utf8(bytes: &[u8]) -> Result<&str, std::str::Utf8Error> {
    std::str::from_utf8(bytes)
}

fn is_utf8_error(e: &iox_v1_query_api::Error) -> bool {
    matches!(e, iox_v1_query_api::Error::Utf8 { .. })
}

let payload = ensure_utf8(&raw).map_err(|e| format!("payload not utf-8: {e}"))?;
let resp = client.post("/query").body(payload.to_owned()).send().await?;

When it happens

Trigger: Sending query bodies, form values, or uploaded files containing invalid UTF-8 byte sequences (e.g. Latin-1 encoded text, binary data, or truncated multibyte characters).

Common situations: Files saved in Windows-1252/ISO-8859-1 encodings uploaded as line protocol, gzip data sent uncompressed/unflagged, or strings containing stray binary bytes.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• authorization failure
• error decoding multipart file upload
• error decoding params from url
• error decoding query body
• invalid mime type ( )

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

Appendix: source

Thrown at core/iox_v1_query_api/src/error.rs:35

pub enum Error {
    /// The requested path has no registered handler.
    #[error("not found: {0}")]
    NoHandler(String),

    #[error("authorization failure: {0}")]
    AuthorizationFailure(String),

    #[error("invalid mime type ({0})")]
    InvalidMimeType(String),

    /// Missing parameters for query
    #[error("missing query parameters 'db' and 'q'")]
    MissingQueryParams,

    #[error("error decoding multipart file upload: {0}")]
    MultipartFile(String),

    #[error("Invalid UTF8: {message} {error}")]
    Utf8 {
        message: &'static str,
        error: String,
    },

    /// Serde decode error
    #[error("error decoding params from url: {0}")]
    SerdeUrlDecoding(#[from] serde_urlencoded::de::Error),

    // SerdeJsonError
    #[error("error decoding query body: {0}")]
    SerdeJson(#[from] serde_json::Error),

    #[error("datafusion error: {0}")]
    Datafusion(#[from] DataFusionError),

    #[error("error in InfluxQL statement: {0}")]
    InfluxqlRewrite(#[from] rewrite::Error),

View on GitHub (pinned to 06200ef96b)