hasura/graphql-engine · error · InvalidConnectorError

invalid connector error with status {status} and {content}

Error message

invalid connector error with status {status} and {content}

What it means

InvalidConnectorError is the structured error type the NDC client produces when a connector responds with an error status and a JSON body. The Display string 'invalid connector error with status {status} and {content}' includes both the HTTP status code and the raw JSON content returned by the connector. It exists so callers can programmatically inspect why a connector request failed instead of parsing an opaque string.

Source

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

    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        if let Some(msg) = self.display_message() {
            write!(f, "{msg}")
        } else {
            write!(
                f,
                "connector error: connector returned status code {status} with message: {}, details: {}",
                self.error_response.message(),
                self.error_response.details(),
                status = self.status
            )
        }
    }
}

impl std::error::Error for ConnectorError {}

#[derive(Debug, Clone, Error)]
#[error("invalid connector error with status {status} and {content}")]
pub struct InvalidConnectorError {
    pub status: reqwest::StatusCode,
    pub content: serde_json::Value,
}

/// Configuration for the API client
/// Contains all the information necessary to perform requests.
#[derive(Debug, Clone)]
pub struct Configuration<'s> {
    pub base_path: &'s reqwest::Url,
    pub client: reqwest::Client,
    pub headers: Cow<'s, HeaderMap<HeaderValue>>,
    pub response_size_limit: Option<usize>,
}

/// POST on /query/explain endpoint
///
/// <https://hasura.github.io/ndc-spec/specification/explain.html?highlight=%2Fexplain#request>

View on GitHub (pinned to 724551b9ae)

Solutions

1. Read .status to classify the failure (4xx = bad request/capability mismatch, 5xx = connector bug) and .content for the connector's message
2. Fix the metadata/query element named in the content JSON (unknown table, unsupported operator, etc.)
3. Ensure the connector is registered and initialized before queries are executed
4. Align engine and connector versions so the NDC spec versions agree
5. File an issue with the connector maintainer including status and content if the message indicates an internal error

Example fix

// before
match client.query(&req).await {
    Err(e) => eprintln!("{e}"), // hard to act on
    _ => {}
}

// after
if let Err(err) = client.query(&req).await {
    if let Some(ice) = err.as_invalid_connector() {
        log::warn!(status = %ice.status, "connector error: {}", ice.content);
    }
}

// Validate the request shape client-side before sending, e.g. ensure
// all referenced collections exist in the connector's schema response:
let schema = ndc_client.get_schema().await?;
for c in query.collections() {
    assert!(schema.collections.contains_key(c), "unknown collection {c}");
}

fn extract_invalid_connector(
    e: &execute::ndc::client::Error,
) -> Option<&InvalidConnectorError> {
    match e {
        execute::ndc::client::Error::Connector(
            ConnectorError::InvalidConnector(ice)
        ) => Some(ice),
        _ => None,
    }
}

if let Err(err) = client.query(&req).await {
    if let Some(ice) = extract_invalid_connector(&err) {
        // structured: ice.status, ice.content
        handle_connector_rejection(ice);
    } else {
        handle_other(err);
    }
}

When it happens

Trigger: Any call through the NDC client (capabilities, schema, query, explain, metrics) that receives a non-2xx HTTP response with a JSON body. The status and content fields carry exactly what the connector returned.

Common situations: Connector rejects a query because of an unknown table/column; capability mismatch after upgrading the engine but not the connector; auth failure surfaced by the connector; connector bug producing 500s with a JSON error body.

Related errors

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

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