biomejs/biome · error

declare var Promise is missing a type annotation

Error message

declare var Promise is missing a type annotation

What it means

This error comes from Biome's xtask codegen, not the runtime library. While lowering the bundled TypeScript global declarations, the tool found a `declare var Promise` whose declarator lacks a `: T` type annotation, which is required to extract and validate the `PromiseConstructor` shape. The build aborts so a malformed ambient Promise declaration never reaches generated code.

Source

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

) -> Result<()> {
    let mut saw_value = false;
    for record in records {
        let DeclarationKind::VariableDeclarator { .. } = &record.kind else {
            continue;
        };
        let declarator = source_cache
            .find_variable_declarator(record)?
            .with_context(|| {
                format!(
                    "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")?;

View on GitHub (pinned to 3835945f06)

Solutions

1. Restore the type annotation on the ambient Promise variable: `declare var Promise: PromiseConstructor;`
2. If the declaration source is generated/vendored, regenerate or re-sync it from upstream instead of editing by hand
3. If an AST change broke `variable_annotation()`, update lower.rs to read the annotation via the new API

Example fix

// before
declare var Promise;
// after
declare var Promise: PromiseConstructor;

// Before running codegen, verify the ambient Promise var carries an annotation
let decl = "declare var Promise: PromiseConstructor;";
assert!(decl.contains(":"), "declare var Promise needs a type annotation");

When it happens

Trigger: Running the global-types codegen (e.g. `cargo codegen global-types` or a full `just gen`) when the source `.d.ts`-style declaration processed by generate_global_types defines `declare var Promise` without a type annotation, or the lowering logic fails to parse the annotation into a TsTypeAnnotation.

Common situations: Editing or vendoring Biome's bundled global declaration file by hand and writing `declare var Promise;` instead of `declare var Promise: PromiseConstructor;`; a parser/AST change making variable_annotation() return None; upgrading the declaration source that dropped the annotation.

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

• Promise global must include declare var Promise
• 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/36ebc0a8677850f4. Report an issue: GitHub.