on-chain database height({on_chain_height}) is less than tar

Error message

on-chain database height({on_chain_height}) is less than target height({target_block_height})

What it means

During rollback_to, after reading current heights, the function refuses to 'roll back' to a target that is above the on-chain database's current height — rollback only moves backward, so a target in the future means the database never reached that height and the request is inconsistent. This guard prevents silently treating a lagging database as rolled back.

Source

Thrown at crates/fuel-core/src/combined_database.rs:524

                    && block_aggregation_storage_rolled_back
                {
                    break;
                }
            }

            #[cfg(not(feature = "rpc"))]
            {
                if on_chain_height == target_block_height
                    && off_chain_height == target_block_height
                    && gas_price_rolled_back
                    && compression_db_rolled_back
                {
                    break;
                }
            }

            if on_chain_height < target_block_height {
                return Err(anyhow::anyhow!(
                    "on-chain database height({on_chain_height}) \
                    is less than target height({target_block_height})"
                ));
            }

            if off_chain_height < target_block_height {
                return Err(anyhow::anyhow!(
                    "off-chain database height({off_chain_height}) \
                    is less than target height({target_block_height})"
                ));
            }

            if let Some(gas_price_chain_height) = gas_price_chain_height
                && gas_price_chain_height < target_block_height
            {
                return Err(anyhow::anyhow!(
                    "gas-price database height({gas_price_chain_height}) \
                    is less than target height({target_block_height})"

View on GitHub (pinned to b9d4d170da)

Solutions

Query the current on-chain height first and pass a target_block_height <= it.
If the on-chain DB is legitimately behind, re-sync it (from peers or snapshot) until it reaches the target, then roll back.
Restore all component databases from one consistent snapshot so heights agree.

Example fix

// before
combined_db.rollback_to(target_block_height, &mut shutdown)?;

// after
let current = combined_db.on_chain().latest_height_from_metadata()?.expect("height");
let target = target_block_height.min(current); // never roll 'forward'
combined_db.rollback_to(target, &mut shutdown)?;

Defensive patterns

Strategy: validation

Validate before calling

let on_chain = combined_db
    .on_chain()
    .latest_height_from_metadata()?
    .ok_or_else(|| anyhow::anyhow!("on-chain DB empty"))?;
if target_block_height > on_chain {
    anyhow::bail!("target {} above on-chain height {}; sync first", target_block_height, on_chain);
}
combined_db.rollback_to(target_block_height, &mut shutdown)?;

Try / catch

match combined_db.rollback_to(target, &mut shutdown) {
    Ok(()) => Ok(()),
    Err(e) if e.to_string().contains("is less than target height") => {
        // database behind target: sync forward, do not retry the same rollback
        anyhow::bail!("database behind target; re-sync to at least {} then retry", target)
    }
    Err(e) => Err(e),
}

Prevention

Compute rollback targets from the database's own current height, never from external chain state.
Clamp targets with target.min(current_height).
Keep component databases at consistent heights by restoring from one snapshot.

When it happens

Trigger: Calling rollback_to with target_block_height greater than the on-chain database's latest committed height — e.g., a wrong target height argument, or database divergence where the on-chain DB is behind what the caller assumed.

Common situations: Misconfigured rollback/re-org target (off-by-one or wrong chain); restoring an on-chain DB from an older snapshot while passing a newer target; mixed-height databases after a crash where components are at inconsistent heights.

Related errors

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