biomejs/biome · error

generated Promise.{} member has unexpected shape

Error message

generated Promise.{} member has unexpected shape

What it means

This invariant failure is raised by Biome's xtask code generator while validating that a generated Promise member (e.g. Promise.prototype.then) matches the shape declared in the codegen manifest: its lowered kind and type reference must equal the expected values. A mismatch means the Web IDL/TS source of truth changed in a way the generator's assumptions no longer cover, so the build stops rather than emitting inconsistent global type definitions.

Source

Thrown at xtask/codegen/src/generate_global_types/compare.rs:312

/// Checks one Promise member and the synthetic callable referenced by that member.
fn assert_promise_method(
    class: &LoweredClass,
    lowered: &LoweredGlobalTypes,
    shape: PromiseMethodShape,
) -> Result<()> {
    let Some(member) = class.member(shape.member_name) else {
        bail!("generated Promise global is missing {}", shape.member_name);
    };
    let expected_kind = if shape.is_static {
        LoweredMemberKind::NamedStatic
    } else {
        LoweredMemberKind::Named { optional: false }
    };
    if member.kind() != &expected_kind
        || member.type_reference() != &LoweredTypeReference::Predefined(shape.member_type_id)
    {
        bail!(
            "generated Promise.{} member has unexpected shape",
            shape.member_name
        );
    }

    let helper = generated_function(lowered, shape.helper_name, shape.helper_id_constant)?;
    if helper.is_async()
        || !helper.type_parameters().is_empty()
        || helper.name() != Some(shape.helper_name)
        || !helper.parameters().is_empty()
        || helper.return_type() != &LoweredTypeReference::Predefined("GLOBAL_INSTANCEOF_PROMISE_ID")
    {
        bail!(
            "generated {} helper has unexpected shape",
            shape.helper_name
        );
    }
    Ok(())

View on GitHub (pinned to 3835945f06)

Solutions

1. Compare the generated Promise member's kind and type reference against shape.member_name in the manifest and update the expected shape (member type id / optional flag) to match the new declaration.
2. If the source declaration is wrong, fix the Promise member declaration in the global typings input instead.
3. After updating expectations, regenerate with `cargo xtask codegen` and commit regenerated files.

// In xtask: pre-validate before compare
fn validate_promise_member(member: &LoweredMember, shape: &PromiseShape) -> Result<()> {
  let expected = LoweredMemberKind::Named { optional: false };
  ensure!(member.kind() == &expected, "member kind drifted for {}", shape.member_name);
  ensure!(member.type_reference() == &LoweredTypeReference::Predefined(shape.member_type_id), "member type drifted for {}", shape.member_name);
  Ok(())
}

match assert_promise_shape(&lowered, &shape) {
  Err(e) if e.to_string().contains("unexpected shape") => {
    eprintln!("Regeneration required: {e}; run `cargo xtask codegen` after updating expectations");
    std::process::exit(1);
  }
  Err(e) => return Err(e),
  Ok(()) => {}
}

When it happens

Trigger: Running `cargo xtask codegen` (global types generation) after the Promise member's declared type or optionality changed upstream, so member.kind() or member.type_reference() no longer matches the expected LoweredMemberKind / Predefined type id in the manifest shape.

Common situations: Updating the bundled lib.global typings or the generator manifest; a contributor edits Promise method signatures in the source declarations without updating the expected shape tables; a codegen refactor changes lowering behavior so Predefined type ids no longer line up.

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

• generated {} helper has unexpected shape
• Promise global must have a type-side declaration
• Promise global must have a value-side declaration
• type aliases are not supported in the Promise global
• unsupported value-side Promise declaration

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