PromiseConstructor must include an interface declaration

Error message

PromiseConstructor must include an interface declaration

What it means

The lowering loop expects at least one record in the PromiseConstructor declaration group to be an interface declaration providing the members to validate and lower. If every record is some other kind (or the group is otherwise interface-less), the saw_constructor_interface flag stays false and this error aborts the codegen.

Source

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

        }
        if declaration.type_parameters().is_some() {
            bail!("PromiseConstructor type parameters are not supported");
        }

        validate_promise_methods(
            &declaration,
            PromiseMemberLocation::Static,
            &mut saw_methods,
        )?;
        for member in declaration.members() {
            if let AnyTsTypeMember::TsConstructSignatureTypeMember(member) = member {
                validate_promise_construct_signature(&member)?;
                saw_construct_signature = true;
            }
        }
    }
    if !saw_constructor_interface {
        bail!("PromiseConstructor must include an interface declaration");
    }
    if !saw_construct_signature {
        bail!("PromiseConstructor is missing a construct signature");
    }
    for (index, specification) in PROMISE_METHOD_SPECIFICATIONS.iter().enumerate() {
        if !saw_methods[index] {
            bail!("Promise is missing {}", specification.global_name);
        }
    }

    let members = std::iter::once(LoweredTypeMember {
        name: Text::from("constructor"),
        kind: LoweredMemberKind::Constructor,
        type_reference: LoweredTypeReference::Predefined("GLOBAL_PROMISE_CONSTRUCTOR_ID"),
    })
    .chain(PROMISE_METHOD_SPECIFICATIONS.map(promise_member))
    .collect();
    globals.push(LoweredGlobal {

View on GitHub (pinned to 3835945f06)

Solutions

Restore `interface PromiseConstructor { ... }` in the lib sources
Update PROMISE declaration handling in lower.rs to locate the interface under a different shape
Check the lib snapshot for accidental interface deletion during a version bump

Example fix

// before (lib .d.ts) — interface removed, only `declare var Promise` remains
declare var Promise: { new <T>(...): Promise<T>; ... };
// after
interface PromiseConstructor { new <T>(...): Promise<T>; all(...): Promise<...>; ... }
declare var Promise: PromiseConstructor;

Defensive patterns

Strategy: validation

Validate before calling

const hasInterface = group.declarations().some(d => d.kind === "Interface");
if (!hasInterface) throw new Error("No interface PromiseConstructor found in the declaration group");

Prevention

Verify the interface survives lib snapshot regeneration
Grep snapshots for `interface PromiseConstructor` after every bump
Never delete the constructor interface when pruning unused declarations

When it happens

Trigger: Running generate_global_types when no `interface PromiseConstructor` exists among the merged declarations, e.g. the interface was renamed, removed, or converted to a type alias.

Common situations: Deleting or renaming the interface during lib snapshot maintenance; a lib version where PromiseConstructor is expressed without an interface declaration.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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