hasura/graphql-engine · error · InvalidConnectorError

invalid connector error: {0}

Error message

invalid connector error: {0}

What it means

This error is thrown by the NDC (Native Data Connector) execute client when the connector returns an error response whose body matches the expected InvalidConnectorError shape (a status code plus JSON content). It wraps the connector's own error payload and surfaces it as 'invalid connector error: {0}'. It means the connector explicitly reported an invalid request or internal problem rather than a well-formed data response.

Source

Thrown at v3/crates/execute/src/ndc/client.rs:55

    #[error("UTF-8 error: {0}")]
    Utf8Error(#[from] std::string::FromUtf8Error),

    #[error("IO error: {0}")]
    IOError(#[from] std::io::Error),

    #[error("invalid connector base URL")]
    InvalidBaseURL,

    #[error("invalid header value characters: {0}")]
    InvalidHeaderValue(#[from] reqwest::header::InvalidHeaderValue),

    #[error("response received from connector is too large: {0}")]
    ResponseTooLarge(String),

    #[error("{0}")]
    Connector(ConnectorError),

    #[error("invalid connector error: {0}")]
    InvalidConnector(InvalidConnectorError),

    #[error("Error while executing pre ndc request plugin: {0}")]
    PreNdcRequestPluginError(#[from] pre_ndc_request_plugin::execute::Error),

    #[error("Error while executing pre ndc response plugin: {0}")]
    PreNdcResponsePluginError(#[from] pre_ndc_response_plugin::execute::Error),
}

impl tracing_util::TraceableError for Error {
    fn visibility(&self) -> tracing_util::ErrorVisibility {
        match self {
            // Invalid connector errors with 5xx status codes are considered user errors
            // (connector implementation issues, not engine issues)
            Self::InvalidConnector(InvalidConnectorError { status, .. })
                if status.is_server_error() =>
            {
                tracing_util::ErrorVisibility::User

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check the embedded InvalidConnectorError.status and content fields to see the connector's own message about what was invalid
2. Verify the connector's capabilities response matches the features used by your metadata/queries (operators, relationships, aggregations)
3. Upgrade or align the connector version with the engine version so the NDC API versions match
4. Reproduce the failing request with curl against the connector directly to inspect what it rejects
5. If the connector is behind a proxy, confirm it isn't rewriting responses into an unexpected error shape

Example fix

// before
let resp = ndc_client.query(args).await; // errors opaque

// after
match ndc_client.query(args).await {
    Ok(rows) => rows,
    Err(execute::ndc::client::Error::Connector(ConnectorError::InvalidConnector(e))) => {
        tracing::error!(status = %e.status, content = ?e.content, "connector rejected request");
        return Err(my::BadRequest.into());
    }
    Err(e) => return Err(e.into()),
}

// Before executing, verify the connector is alive and its capabilities
// match what your query needs:
let caps = ndc_client.get_capabilities().await?;
if !caps.supports_relationships && query_has_relationships(&q) {
    return Err(MyError::UnsupportedFeature("relationships"));
}

fn is_invalid_connector_err(e: &execute::ndc::client::Error) -> bool {
    matches!(e, execute::ndc::client::Error::Connector(
        ConnectorError::InvalidConnector(_)
    ))
}

match ndc_client.query(req).await {
    Ok(rows) => Ok(rows),
    Err(e @ execute::ndc::client::Error::Connector(
        ConnectorError::InvalidConnector(ice)
    )) => {
        tracing::warn!(status = %ice.status, content = ?ice.content, "connector rejected");
        Err(e.into())
    }
    Err(e) => Err(e.into()),
}

When it happens

Trigger: An HTTP request to a native data connector (query/explanations/metrics capabilities or query execution) returns a non-success status whose body deserializes into InvalidConnectorError (status + JSON content). Commonly triggered by malformed NDC request JSON, unsupported capabilities, or connector-side validation failures.

Common situations: Connector version that doesn't support a capability the engine sends; schema/capabilities mismatch between the engine and the connector; connector receives a query referencing relationships or operators it doesn't implement; misconfigured connector endpoint returning structured error JSON.

Related errors

• error from data source: {}
• {0}
• invalid connector error with status {status} and {content}
• Relationship '{name}' is either remote or not having 'relati
• The aggregation function {aggregation_function} operating ov

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/19f37492a9c92231. Report an issue: GitHub.