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.

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)

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 `message_block_height` is higher than `commit_block_heig
• The count of leaves - messages is zero

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