{"record":{"id":"19f37492a9c92231","repo":"hasura/graphql-engine","slug":"invalid-connector-error-0","errorCode":null,"errorMessage":"invalid connector error: {0}","messagePattern":"invalid connector error: (.+?)","errorType":"http","errorClass":"InvalidConnectorError","httpStatus":null,"severity":"error","filePath":"v3/crates/execute/src/ndc/client.rs","lineNumber":55,"sourceCode":"    #[error(\"UTF-8 error: {0}\")]\n    Utf8Error(#[from] std::string::FromUtf8Error),\n\n    #[error(\"IO error: {0}\")]\n    IOError(#[from] std::io::Error),\n\n    #[error(\"invalid connector base URL\")]\n    InvalidBaseURL,\n\n    #[error(\"invalid header value characters: {0}\")]\n    InvalidHeaderValue(#[from] reqwest::header::InvalidHeaderValue),\n\n    #[error(\"response received from connector is too large: {0}\")]\n    ResponseTooLarge(String),\n\n    #[error(\"{0}\")]\n    Connector(ConnectorError),\n\n    #[error(\"invalid connector error: {0}\")]\n    InvalidConnector(InvalidConnectorError),\n\n    #[error(\"Error while executing pre ndc request plugin: {0}\")]\n    PreNdcRequestPluginError(#[from] pre_ndc_request_plugin::execute::Error),\n\n    #[error(\"Error while executing pre ndc response plugin: {0}\")]\n    PreNdcResponsePluginError(#[from] pre_ndc_response_plugin::execute::Error),\n}\n\nimpl tracing_util::TraceableError for Error {\n    fn visibility(&self) -> tracing_util::ErrorVisibility {\n        match self {\n            // Invalid connector errors with 5xx status codes are considered user errors\n            // (connector implementation issues, not engine issues)\n            Self::InvalidConnector(InvalidConnectorError { status, .. })\n                if status.is_server_error() =>\n            {\n                tracing_util::ErrorVisibility::User","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/v3/crates/execute/src/ndc/client.rs#L37-L73","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the embedded InvalidConnectorError.status and content fields to see the connector's own message about what was invalid","Verify the connector's capabilities response matches the features used by your metadata/queries (operators, relationships, aggregations)","Upgrade or align the connector version with the engine version so the NDC API versions match","Reproduce the failing request with curl against the connector directly to inspect what it rejects","If the connector is behind a proxy, confirm it isn't rewriting responses into an unexpected error shape"],"exampleFix":"// before\nlet resp = ndc_client.query(args).await; // errors opaque\n\n// after\nmatch ndc_client.query(args).await {\n    Ok(rows) => rows,\n    Err(execute::ndc::client::Error::Connector(ConnectorError::InvalidConnector(e))) => {\n        tracing::error!(status = %e.status, content = ?e.content, \"connector rejected request\");\n        return Err(my::BadRequest.into());\n    }\n    Err(e) => return Err(e.into()),\n}","handlingStrategy":"try-catch","validationCode":"// Before executing, verify the connector is alive and its capabilities\n// match what your query needs:\nlet caps = ndc_client.get_capabilities().await?;\nif !caps.supports_relationships && query_has_relationships(&q) {\n    return Err(MyError::UnsupportedFeature(\"relationships\"));\n}","typeGuard":"fn is_invalid_connector_err(e: &execute::ndc::client::Error) -> bool {\n    matches!(e, execute::ndc::client::Error::Connector(\n        ConnectorError::InvalidConnector(_)\n    ))\n}","tryCatchPattern":"match ndc_client.query(req).await {\n    Ok(rows) => Ok(rows),\n    Err(e @ execute::ndc::client::Error::Connector(\n        ConnectorError::InvalidConnector(ice)\n    )) => {\n        tracing::warn!(status = %ice.status, content = ?ice.content, \"connector rejected\");\n        Err(e.into())\n    }\n    Err(e) => Err(e.into()),\n}","preventionTips":["Run connector capability checks before issuing feature-dependent queries","Pin engine and connector to compatible versions and test upgrades together","Log status+content on every InvalidConnector to build a fix map quickly"],"tags":["rust","ndc","connector","http-client","data-connector"],"backgroundTag":"ndc-connector-error","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}