FuelLabs/fuel-core · warning

Failed to wait for the required fuel block height

Error message

Failed to wait for the required fuel block height: {}

What it means

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.

Solutions

1. Retry the GraphQL request once the node is healthy and producing blocks.
2. Confirm node health and sync status first; if the height is already reached, the request should succeed immediately.
3. Reduce the wait window (timeout config) so requests fail fast during node instability.

// Client side: verify the node already reports the required height before querying.
let current: u32 = graphql_query("{ chain { latestBlock { header { height } } } }")?;
if current < required_height {
    wait_for_node_height(required_height).await?;
}
// then issue the @requiredFuelBlockHeight query

// Client side: one bounded retry, then surface a node-health error.
for attempt in 0..2 {
    match run_query_with_required_height(required_height).await {
        Ok(r) => return Ok(r),
        Err(e) if e.contains("Failed to wait for the required fuel block height") && attempt == 0 => {
            health_check_node().await?; // node's subscription service was torn down
            continue;
        }
        Err(e) => return Err(e),
    }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• The block height subscription channel was closed
• Timeout while waiting for the required fuel block height
• {error}
• The count of leaves - messages is zero
• The `message_block_height` is higher than…

AI-assisted analysis of FuelLabs/fuel-core@b9d4d170da (2026-08-16). Data as JSON: /api/errors/0969861ed952f502. Report an issue: GitHub.

Appendix: source

Thrown at crates/fuel-core/src/graphql_api/extensions/required_fuel_block_height.rs:244

    error
        .extensions
        .as_mut()
        .expect("Inserted above; qed")
        .set(FUEL_BLOCK_HEIGHT_PRECONDITION_FAILED, Value::Boolean(true));

    error
}

async fn await_block_height(
    block_height_subscriber: &block_height_subscription::Subscriber,
    block_height: &BlockHeight,
    timeout: &Duration,
) -> anyhow::Result<()> {
    tokio::select! {
        biased;
        block_height_res = block_height_subscriber.wait_for_block_height(*block_height) => {
            block_height_res.map_err(|e| {
                anyhow::anyhow!(
                    "Failed to wait for the required fuel block height: {}",
                    e
                )})
        },
        _ = tokio::time::sleep(*timeout) => {
            Err(anyhow::anyhow!(
                "Timeout while waiting for the required fuel block height: {}",
                block_height
            ))
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::graphql_api::extensions::unify_response;
    use async_graphql::Response;

View on GitHub (pinned to b9d4d170da)