Promise global must include an interface declaration

Error message

Promise global must include an interface declaration

What it means

After walking all declarations in the 'Promise' global group, the codegen checks that at least one was an interface (the `interface Promise<T>` declaration). If none was seen, the Promise instance-side methods cannot be anchored to a type and lowering fails with this error.

Source

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

        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,
        )?;
    }
    if !saw_promise_interface {
        bail!("Promise global must include an interface declaration");
    }

    let Some(constructor_group) = manifest.global_group("PromiseConstructor") else {
        bail!("Promise global value side references missing PromiseConstructor group");
    };
    if !constructor_group.has_role(GlobalDeclarationRole::Type) {
        bail!("PromiseConstructor must have a type-side declaration");
    }

    let mut saw_constructor_interface = false;
    let mut saw_construct_signature = false;
    for record in constructor_group.declarations() {
        match &record.kind {
            DeclarationKind::Interface => saw_constructor_interface = true,
            DeclarationKind::TypeAlias => {
                bail!("type aliases are not supported in PromiseConstructor")
            }
            DeclarationKind::DeclareFunction

View on GitHub (pinned to 3835945f06)

Solutions

Ensure the global typings source declares `interface Promise<T>` inside the Promise global group.
Verify the manifest builder classifies that interface with DeclarationKind::Interface in the Promise group.
Regenerate and re-run `cargo xtask codegen`.

Defensive patterns

Strategy: validation

Validate before calling

// Confirm an interface record exists in the Promise group
fn has_promise_interface(group: &GlobalGroup) -> bool {
  group.declarations().iter().any(|r| matches!(r.kind, DeclarationKind::Interface))
}
if !has_promise_interface(promise_group) { bail!("Promise group lacks interface declaration"); }

Try / catch

if let Err(e) = lower_promise_globals(&manifest, &mut globals, &source_cache) {
  if e.to_string().contains("must include an interface declaration") {
    eprintln!("Restore `interface Promise<T>` in the Promise global group and rerun codegen");
    std::process::exit(1);
  }
  return Err(e.into());
}

Prevention

Keep `interface Promise<T>` present whenever Promise declarations are edited.
Add a manifest-level assertion that the Promise group contains an Interface record.
Check manifest grouping after changes to declaration parsing/extraction.
Inspect regenerated manifests in code review.

When it happens

Trigger: Running `cargo xtask codegen` when the Promise group's records contain no DeclarationKind::Interface — e.g. the interface was removed, renamed away from the group, or misclassified during manifest construction.

Common situations: Deleting `interface Promise<T>` while keeping the `declare var Promise`; a parsing/role-extraction change stops mapping the interface record into the Promise group; moving the interface into another global 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/84e60db2e34d31f0. Report an issue: GitHub.