biomejs/biome · error

Promise global must have a value-side declaration

Error message

Promise global must have a value-side declaration

What it means

Biome's xtask codegen requires the 'Promise' global declaration group to include a value-side declaration (the `declare var Promise: PromiseConstructor` style record). When the group exists but carries no Value role declaration, the Promise global's runtime value cannot be lowered and the generator bails.

Source

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

    ));

    Ok(())
}

/// Validates the selected declarations before emitting the resolver's reduced Promise projection.
fn lower_promise_globals(
    manifest: &GlobalManifest,
    source_cache: &mut ParsedSourceCache,
    globals: &mut Vec<LoweredGlobal>,
) -> Result<()> {
    let Some(promise_group) = manifest.global_group("Promise") else {
        return Ok(());
    };
    if !promise_group.has_role(GlobalDeclarationRole::Type) {
        bail!("Promise global must have a type-side declaration");
    }
    if !promise_group.has_role(GlobalDeclarationRole::Value) {
        bail!("Promise global must have a value-side declaration");
    }
    validate_promise_constructor_reference(promise_group.declarations(), source_cache)?;

    let mut saw_promise_interface = false;
    let mut saw_methods = [false; PROMISE_METHOD_COUNT];
    for record in promise_group.declarations() {
        match &record.kind {
            DeclarationKind::Interface => saw_promise_interface = true,
            DeclarationKind::VariableDeclarator { .. } => continue,
            DeclarationKind::TypeAlias => {
                bail!("type aliases are not supported in the Promise global")
            }
            DeclarationKind::DeclareFunction | DeclarationKind::ImportEquals => {
                bail!("unsupported value-side Promise declaration")
            }
        }

        let declaration = source_cache

View on GitHub (pinned to 3835945f06)

Solutions

  1. Restore the value-side declaration for Promise in the global typings source (e.g. `declare var Promise: PromiseConstructor;`).
  2. Verify declaration-role extraction marks that record with GlobalDeclarationRole::Value.
  3. Regenerate and re-run `cargo xtask codegen` to confirm the group passes both role checks.
Defensive patterns

Strategy: validation

Validate before calling

// Ensure the value-side declaration exists before lowering
fn has_value_promise(group: &GlobalGroup) -> bool {
  group.has_role(GlobalDeclarationRole::Value)
    && group.declarations().iter().any(|r| matches!(r.kind, DeclarationKind::VariableDeclarator { .. }))
}
if !has_value_promise(&promise_group) { bail!("add `declare var Promise: PromiseConstructor;`"); }

Try / catch

match lower_promise_globals(&manifest, &mut globals, &source_cache) {
  Err(e) if e.to_string().contains("value-side declaration") => {
    eprintln!("Restore `declare var Promise: PromiseConstructor;` and rerun `cargo xtask codegen`");
    std::process::exit(1);
  }
  r => r?,
}

Prevention

When it happens

Trigger: Running `cargo xtask codegen` when the manifest's 'Promise' group has a Type-role record but no Value-role record — e.g. the `declare var Promise: PromiseConstructor;` line is missing from the global typings input or was not recognized as a VariableDeclarator/declaration role.

Common situations: Deleting or renaming the Promise value declaration while editing globals; a parser change stops classifying `declare var Promise` as a value-side declaration; roles were manually curated and Value was dropped.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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