Promise global must have a type-side declaration

Error message

Promise global must have a type-side declaration

What it means

During Promise global lowering, Biome's xtask codegen requires the 'Promise' global declaration group to include a type-side declaration (the Promise interface itself). If the group exists but carries no Type role declaration, lowering cannot produce the Promise global type and fails with this message.

Source

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

        Box::new([LoweredTypeReference::Predefined("GLOBAL_U_ID")]),
        "GLOBAL_MAP_CALLBACK_ID",
        "GLOBAL_INSTANCEOF_ARRAY_U_ID",
    ));

    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")
            }

View on GitHub (pinned to 3835945f06)

Solutions

Ensure the global typings source contains a type-side Promise declaration (the `interface Promise<T>` / `declare var Promise` type portion) and that role extraction tags it as Type.
Regenerate the declaration manifest and re-run `cargo xtask codegen`.
If the group is intentionally absent, note the early return only happens when the whole 'Promise' group is missing; a group must always include both roles.

Defensive patterns

Strategy: validation

Validate before calling

// Check group roles before lowering
fn require_roles(group: &GlobalGroup, name: &str) -> Result<()> {
  ensure!(group.has_role(GlobalDeclarationRole::Type), "{name} missing type-side declaration");
  ensure!(group.has_role(GlobalDeclarationRole::Value), "{name} missing value-side declaration");
  Ok(())
}

Try / catch

match lower_promise_globals(&manifest, &mut globals, &source_cache) {
  Err(e) if e.to_string().contains("type-side declaration") => {
    eprintln!("Restore `interface Promise<T>` in the Promise global group, then rerun codegen: {e}");
    std::process::exit(1);
  }
  r => r?,
}

Prevention

Keep `interface Promise<T>` (type side) and `declare var Promise` (value side) together in the global typings.
Never remove role tags when touching declaration-role extraction code.
Add a manifest sanity test asserting both roles exist for key globals (Promise, PromiseConstructor).
Regenerate the manifest after any edits to declaration parsing.

When it happens

Trigger: Running `cargo xtask codegen` when the declaration manifest's 'Promise' group lacks any record with GlobalDeclarationRole::Type — e.g. the Promise interface was removed or its role tagging was lost when editing the global typings source.

Common situations: Refactoring how declaration roles are extracted from lib.global source files; accidentally deleting or moving the Promise interface declaration; mis-parsing that drops the type-side record from the group.

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/fe9a49bcdc305e52. Report an issue: GitHub.