What causes "unsupported value-side Promise declaration" in biomejs/biome?

Replace the `declare function`/`import equals` form with the canonical value-side form: `declare var Promise: PromiseConstructor;` (plus the Promise interface).

biomejs/biome · error

unsupported value-side Promise declaration

Error message

unsupported value-side Promise declaration

What it means

Inside the 'Promise' global group, only interface declarations and variable declarators are supported. A `declare function` or `import equals` record on the value side cannot be lowered into the generated Promise global, so the codegen stops with this error.

Source

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

    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
            .find_interface_declaration(record)?
            .with_context(|| {
                format!(
                    "failed to find interface declaration {} at {:?}",
                    record.declared_name.text(),
                    record.text_range
                )
            })?;
        validate_promise_interface(&declaration)?;
        validate_promise_methods(
            &declaration,
            PromiseMemberLocation::Instance,
            &mut saw_methods,
        )?;

View on GitHub (pinned to 3835945f06)

Solutions

Replace the `declare function`/`import equals` form with the canonical value-side form: `declare var Promise: PromiseConstructor;` (plus the Promise interface).
Remove any import-equals aliasing of Promise from the global declarations.
Regenerate and re-run `cargo xtask codegen`.

Example fix

// before
declare function Promise<T>(executor: ...): Promise<T>;
// after
declare var Promise: PromiseConstructor;

Defensive patterns

Strategy: validation

Validate before calling

// Reject unsupported value-side kinds before lowering
fn assert_supported_value_kinds(group: &GlobalGroup) -> Result<()> {
  for r in group.declarations() {
    ensure!(!matches!(r.kind, DeclarationKind::DeclareFunction | DeclarationKind::ImportEquals),
      "unsupported Promise declaration kind");
  }
  Ok(())
}

Try / catch

match lower_promise_globals(&manifest, &mut globals, &source_cache) {
  Err(e) if e.to_string().contains("unsupported value-side Promise declaration") => {
    eprintln!("Use `declare var Promise: PromiseConstructor;` instead of declare-function/import-equals: {e}");
    std::process::exit(1);
  }
  r => r?,
}

Prevention

Always declare Promise's value side as a variable declarator referencing PromiseConstructor.
Avoid `declare function Promise(...)` and `import Promise = ...` forms in globals.
Document the allowed declaration kinds for the Promise group for contributors.
Run codegen locally before pushing globals changes.

When it happens

Trigger: Running `cargo xtask codegen` when a Promise-group record has DeclarationKind::DeclareFunction or DeclarationKind::ImportEquals — e.g. the typings define Promise via `declare function Promise(...)` or an `import Promise = ...` alias instead of `declare var`.

Common situations: Reimplementing the Promise global from a spec that uses function-style declarations; migrating declaration style while editing globals; an import-equals alias introduced during a refactor.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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