{"record":{"id":"0969861ed952f502","repo":"FuelLabs/fuel-core","slug":"failed-to-wait-for-the-required-fuel-block-height","errorCode":null,"errorMessage":"Failed to wait for the required fuel block height: {}","messagePattern":"Failed to wait for the required fuel block height: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"crates/fuel-core/src/graphql_api/extensions/required_fuel_block_height.rs","lineNumber":244,"sourceCode":"    error\n        .extensions\n        .as_mut()\n        .expect(\"Inserted above; qed\")\n        .set(FUEL_BLOCK_HEIGHT_PRECONDITION_FAILED, Value::Boolean(true));\n\n    error\n}\n\nasync fn await_block_height(\n    block_height_subscriber: &block_height_subscription::Subscriber,\n    block_height: &BlockHeight,\n    timeout: &Duration,\n) -> anyhow::Result<()> {\n    tokio::select! {\n        biased;\n        block_height_res = block_height_subscriber.wait_for_block_height(*block_height) => {\n            block_height_res.map_err(|e| {\n                anyhow::anyhow!(\n                    \"Failed to wait for the required fuel block height: {}\",\n                    e\n                )})\n        },\n        _ = tokio::time::sleep(*timeout) => {\n            Err(anyhow::anyhow!(\n                \"Timeout while waiting for the required fuel block height: {}\",\n                block_height\n            ))\n        }\n    }\n}\n\n#[cfg(test)]\nmod tests {\n    use super::*;\n    use crate::graphql_api::extensions::unify_response;\n    use async_graphql::Response;","sourceCodeStart":226,"sourceCodeEnd":262,"githubUrl":"https://github.com/FuelLabs/fuel-core/blob/b9d4d170da3a31c9ace5f963d633b326348e0d42/crates/fuel-core/src/graphql_api/extensions/required_fuel_block_height.rs#L226-L262","documentation":"The @requiredFuelBlockHeight GraphQL extension's await_block_height wraps block_height_subscriber.wait_for_block_height; if that inner future fails (typically the 'block height subscription channel was closed' error), it is wrapped with this message. It signals the node's block-height notification machinery could not deliver the awaited height, not that the height itself is invalid.","triggerScenarios":"A GraphQL query/mutation annotated with @requiredFuelBlockHeight waits for a height and the underlying subscription service drops its handler channel (shutdown or cleanup) before the height arrives.","commonSituations":"Requests held open waiting for future blocks while the node restarts or the subscription service is torn down; load hitting a node that is stopping.","solutions":["Retry the GraphQL request once the node is healthy and producing blocks.","Confirm node health and sync status first; if the height is already reached, the request should succeed immediately.","Reduce the wait window (timeout config) so requests fail fast during node instability."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Client side: verify the node already reports the required height before querying.\nlet current: u32 = graphql_query(\"{ chain { latestBlock { header { height } } } }\")?;\nif current < required_height {\n    wait_for_node_height(required_height).await?;\n}\n// then issue the @requiredFuelBlockHeight query","typeGuard":null,"tryCatchPattern":"// Client side: one bounded retry, then surface a node-health error.\nfor attempt in 0..2 {\n    match run_query_with_required_height(required_height).await {\n        Ok(r) => return Ok(r),\n        Err(e) if e.contains(\"Failed to wait for the required fuel block height\") && attempt == 0 => {\n            health_check_node().await?; // node's subscription service was torn down\n            continue;\n        }\n        Err(e) => return Err(e),\n    }\n}","preventionTips":["Gate height-pinned queries on the node's current height first.","Retry once after a node health check; persistent failure means the node is stopping.","Prefer short timeouts so stopped nodes fail fast rather than piling up requests."],"tags":["graphql","extension","subscription","retry","rust"],"backgroundTag":null,"analyzedSha":"b9d4d170da3a31c9ace5f963d633b326348e0d42","analyzedAt":"2026-08-16T08:56:42.692Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}