type aliases are not supported in the Promise global

Error message

type aliases are not supported in the Promise global

What it means

The Promise global lowering pipeline only accepts interfaces and variable declarators inside the 'Promise' declaration group. A TypeScript type alias found there cannot be represented by the generated Promise global code, so lowering aborts with this message.

Source

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

    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
            .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,

View on GitHub (pinned to 3835945f06)

Solutions

Remove the type alias from the Promise global group or convert it back into an interface declaration.
Move the alias to a location outside the Promise global group if it is needed elsewhere.
Regenerate the manifest and re-run `cargo xtask codegen`.

Example fix

// before (inside Promise global declarations)
type PromiseResult<T> = T | undefined;
// after
interface PromiseResult<T> { /* members */ }

Defensive patterns

Strategy: validation

Validate before calling

// Reject aliases inside the Promise group before lowering
fn assert_no_type_aliases(group: &GlobalGroup) -> Result<()> {
  ensure!(!group.declarations().iter().any(|r| matches!(r.kind, DeclarationKind::TypeAlias)),
    "type aliases are not allowed in the Promise global");
  Ok(())
}

Try / catch

if let Err(e) = lower_promise_globals(&manifest, &mut globals, &source_cache) {
  if e.to_string().contains("type aliases are not supported") {
    eprintln!("Convert the alias to an interface or move it out of the Promise group: {e}");
    std::process::exit(1);
  }
  return Err(e.into());
}

Prevention

Never add `type X = ...` declarations inside the Promise global group.
Model new shape abstractions as interfaces, which lowering supports.
Add a fixture test covering allowed declaration kinds in the Promise group.
Review generated manifest contents when adding declarations.

When it happens

Trigger: Running `cargo xtask codegen` when a record in the Promise global group has DeclarationKind::TypeAlias — i.e. someone added `type Promise... = ...` inside the Promise global declaration section of the global typings input.

Common situations: Adding a convenience alias (e.g. `type PromiseLikeResult = ...`) in the Promise block; an upstream lib edit converts an interface into a type alias; refactoring declarations moves an alias into the Promise group.

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