databendlabs/databend · error · ErrorCode

ER_UNKNOWN_ERROR

ER_UNKNOWN_ERROR

Error message

ER_UNKNOWN_ERROR: {error}

What it means

When query execution fails, the query result writer reports the error to the MySQL client as ER_UNKNOWN_ERROR carrying the internal ErrorCode message. Aborted query/session errors are special-cased to ER_ABORTING_CONNECTION; everything else falls into this generic bucket. It also marks the session's txn manager as failed.

Solutions

1. Parse the detail after 'ER_UNKNOWN_ERROR: ' — it contains the true internal error message and often a code.
2. Check server logs for 'OnQuery Error' with the same timestamp to find the root cause.
3. If an abort/kill is involved, re-run the query; check for admin KILL statements or timeouts.
4. Fix the underlying query/storage issue indicated in the message (syntax, permissions, memory limits).

// client-side: extract the underlying cause from the packet
try:
    cursor.execute(query)
except mysql.connector.Error as e:
    cause = str(e).split('ER_UNKNOWN_ERROR: ', 1)[-1]
    if 'aborted' in cause.lower():
        reconnect_and_retry()
    else:
        raise RuntimeError(cause) from e

When it happens

Trigger: Any Err(ErrorCode) returned while writing a query result via QueryResultWriter::write or ok() — execution errors, serialization failures while streaming data, or aborts not classified as ABORTED_QUERY/ABORTED_SESSION.

Common situations: Query failures from bad SQL or permissions, output format serialization errors, kill/race issues surfacing as other codes, storage timeouts during result streaming.

Related errors

• ER_UNKNOWN_ERROR
• expect InvalidReply
• mysql handler should be authed when call
• status code: , msg

AI-assisted analysis of databendlabs/databend@288d84d76e (2026-09-11). Data as JSON: /api/errors/bb2ce9e70984b414. Report an issue: GitHub.

Appendix: source

Thrown at src/query/service/src/servers/mysql/writers/query_result_writer.rs:397

                let info = query_result
                    .extra_info
                    .map(|r| r.progress_info())
                    .unwrap_or_default();
                row_writer.finish_with_info(&info).await?;

                Ok(())
            }
        }
    }

    #[async_backtrace::framed]
    async fn err(&self, error: &ErrorCode, writer: QueryResultWriter<'a, W>) -> Result<()> {
        self.session.txn_mgr().lock().set_fail();
        if error.code() != ErrorCode::ABORTED_QUERY && error.code() != ErrorCode::ABORTED_SESSION {
            error!("OnQuery Error: {:?}", error);
            writer
                .error(ErrorKind::ER_UNKNOWN_ERROR, error.to_string().as_bytes())
                .await?;
        } else {
            writer
                .error(
                    ErrorKind::ER_ABORTING_CONNECTION,
                    error.to_string().as_bytes(),
                )
                .await?;
        }

        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

View on GitHub (pinned to 288d84d76e)