biomejs/biome · error

Promise global must include declare var Promise

Error message

Promise global must include declare var Promise

What it means

The global-types lowering step validates that the Promise global section contains at least one value declaration. If, after processing all members, no `declare var Promise` was seen (only type-side members like interfaces or a bare namespace), the tool bails because the constructor value itself is missing. This guarantees generated code models the Promise constructor value, not just its types.

Source

Thrown at xtask/codegen/src/generate_global_types/lower.rs:1079

                    "failed to find variable declaration {} at {:?}",
                    record.declared_name.text(),
                    record.text_range
                )
            })?;
        let Some(AnyTsVariableAnnotation::TsTypeAnnotation(annotation)) =
            declarator.variable_annotation()
        else {
            bail!("declare var Promise is missing a type annotation");
        };
        validate_reference_type(
            &annotation.ty()?,
            "PromiseConstructor",
            "declare var Promise",
        )?;
        saw_value = true;
    }
    if !saw_value {
        bail!("Promise global must include declare var Promise");
    }
    Ok(())
}

/// Requires the executor and return shapes represented by the synthetic constructor helper.
fn validate_promise_construct_signature(member: &TsConstructSignatureTypeMember) -> Result<()> {
    single_type_parameter_name(member.type_parameters(), "Promise constructor")?;

    let mut parameters = member.parameters()?.items().into_iter();
    let executor = required_formal_parameter(
        parameters.next(),
        "Promise constructor",
        "one executor parameter",
    )?;
    if parameters.next().is_some() || executor.question_mark_token().is_some() {
        bail!("Promise constructor must have one required executor parameter");
    }
    let executor_type = executor

View on GitHub (pinned to 3835945f06)

Solutions

1. Re-add the ambient value: `declare var Promise: PromiseConstructor;` in the global declaration section
2. Verify the lowering loop actually visits the variable declarator and sets saw_value (check that the member kind matches what lower.rs matches on)
3. Regenerate/sync the bundled global declarations if they were hand-edited

Example fix

// before
declare interface PromiseConstructor { /* ... */ }
// after
declare interface PromiseConstructor { /* ... */ }
declare var Promise: PromiseConstructor;

// Check the Promise global block contains the constructor value
let src = std::fs::read_to_string("globals.d.ts")?;
assert!(src.contains("declare var Promise"), "Promise global block must declare the var");

When it happens

Trigger: Running the global-types codegen when the Promise global block's declarations were removed, renamed (e.g. `declare var PromiseLike` only), or failed the earlier annotation check so `saw_value` was never set to true.

Common situations: Accidentally deleting the `declare var Promise` line while editing the bundled .d.ts source; refactoring the lowering loop so the Promise variable no longer matches; upstream declaration changes removing the var.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• declare var Promise is missing a type annotation
• Promise constructor must have one required executor paramete
• Promise constructor executor must be a function type
• Promise constructor executor must not be generic
• Promise constructor executor must return void

AI-assisted analysis of biomejs/biome@3835945f06 (2026-09-13). Data as JSON: /api/errors/73b6bb6e1adf76cc. Report an issue: GitHub.