influxdata/influxdb · error · PlannerError

InfluxQL internal error

Error message

InfluxQL internal error: {0}

What it means

PlannerError::Internal wraps unexpected InfluxQL planning failures with the message 'InfluxQL internal error: {0}'. It marks bugs in IOx's InfluxQL planner rather than user mistakes; clients are told to treat this prefix as an indicator of an internal error.

Solutions

1. Read the wrapped String for the concrete internal cause
2. File a bug with the offending InfluxQL query and full error
3. Try simplifying or rewriting the query to avoid the unsupported construct
4. Check for version mismatches between the InfluxQL parser and IOx planner crates

Example fix

// before
let plan = make_planner().plan(query)?; // Internal("unhandled SHOW TAG VALUES")
// after
match make_planner().plan(query) {
    Err(e @ DataFusionError::Plan(msg)) if msg.starts_with("InfluxQL internal error") => {
        // report/rewrite query; see msg for the failing construct
    }
    other => other?,
}

// no cheap pre-check; ensure the query only uses supported InfluxQL constructs

match planner.plan(&statement) {
    Err(e) if e.to_string().starts_with("InfluxQL internal error") => {
        report_bug(&e); fallback_plan()
    }
    other => other,
}

When it happens

Trigger: Calling InfluxQL planning APIs with query shapes the planner's invariants do not cover, or hitting unreachable code paths (bad internal state, unmatched AST variants).

Common situations: New/unsupported InfluxQL syntax reaching an unimplemented planner branch; version drift between the influxql parser crate and the IOx planner; bugs where show-tag-values/subqueries hit unhandled cases.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Arrow error
• Bind parameter ' ' was provided but not found in the…
• Bind parameter ' ' was referenced in the InfluxQL statement…
• can only perform queries on a single database
• Database not found

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

Appendix: source

Thrown at core/iox_query_influxql/src/error.rs:36

pub(crate) fn not_implemented<T>(feature: impl Into<String>) -> Result<T> {
    Err(map::not_implemented(feature))
}

/// Functions that return a DataFusionError rather than a `Result<T, DataFusionError>`
/// making them convenient to use with functions like `map_err`.
pub(crate) mod map {
    use datafusion::common::DataFusionError;
    use influxdb_influxql_parser::time_range::ExprError;
    use thiserror::Error;

    #[derive(Debug, Error)]
    enum PlannerError {
        /// An unexpected error that represents a bug in IOx.
        ///
        /// The message is prefixed with `InfluxQL internal error: `,
        /// which may be used by clients to identify internal InfluxQL
        /// errors.
        #[error("InfluxQL internal error: {0}")]
        Internal(String),
    }

    /// An error that was the result of an invalid InfluxQL query.
    pub(crate) fn query(s: impl Into<String>) -> DataFusionError {
        DataFusionError::Plan(s.into())
    }

    /// An error that was the result of an invalid InfluxQL parameter.
    pub(crate) fn params(s: impl Into<String>) -> DataFusionError {
        DataFusionError::Plan(s.into())
    }

    /// An unexpected error whilst planning that represents a bug in IOx.
    pub(crate) fn internal(s: impl Into<String>) -> DataFusionError {
        DataFusionError::External(Box::new(PlannerError::Internal(s.into())))
    }

View on GitHub (pinned to 06200ef96b)