pulumi/pulumi · error

Boilerplate must define a `BaseOptions` type.

Error message

Boilerplate must define a `BaseOptions` type.

What it means

This error comes from a code-generation script in the Pulumi automation tools that reads a TypeScript 'boilerplate' source file using ts-morph. The script requires the boilerplate to export a type alias named `BaseOptions`, which serves as the base options type for generated CLI command option types. If the boilerplate was edited and the `BaseOptions` type alias was renamed, removed, or made non-exported, generation aborts with this error.

Solutions

  1. Add (or restore) an exported `export type BaseOptions = { ... };` type alias to the boilerplate source file
  2. Check that the name is exactly `BaseOptions` (case-sensitive) and declared at the top level of the file
  3. If it was intentionally renamed, update the generator at sdk/nodejs/tools/automation/src/index.ts to look up the new name

Example fix

// before (boilerplate.ts)
export type CliOptions = { verbose?: boolean };

// after
export type BaseOptions = { verbose?: boolean };
Defensive patterns

Strategy: validation

Validate before calling

import { Project, SourceFile } from "ts-morph";
function hasBaseOptions(source: SourceFile): boolean {
  return source.getTypeAlias("BaseOptions") !== undefined;
}
// call before running the generator:
if (!hasBaseOptions(source)) throw new Error("boilerplate missing BaseOptions");

Type guard

function isDefined<T>(v: T | undefined): v is T {
  return v !== undefined;
}
const baseOptionsType = source.getTypeAlias("BaseOptions");
if (isDefined(baseOptionsType)) { /* safe to use */ }

Try / catch

try {
  project.saveSync();
} catch (e) {
  if (String(e).includes("BaseOptions")) {
    console.error("Boilerplate template drift: restore `export type BaseOptions`");
  }
  throw e;
}

Prevention

When it happens

Trigger: Running the automation tooling's generate step (src/index.ts) against a boilerplate .ts file that contains no top-level type alias named exactly `BaseOptions` — e.g. after refactoring, renaming to `CliBaseOptions`, or deleting it.

Common situations: Developers refactoring the boilerplate template, removing 'unused' types flagged by linters, or renaming types during a cleanup pass; also occurrs when a new boilerplate file is swapped in that never defined `BaseOptions`.

Related errors


AI-assisted analysis of pulumi/pulumi@793f7b2e16 (2026-08-31). Data as JSON: /api/errors/81bf833a267919b4. Report an issue: GitHub.

Appendix: source

Thrown at sdk/nodejs/tools/automation/src/index.ts:68

    const specification: string = path.resolve(process.cwd(), process.argv[2]);
    const boilerplate: string = path.resolve(process.cwd(), process.argv[3] ?? path.join("boilerplate", "testing.ts"));
    const output: string = path.resolve(process.cwd(), process.argv[4] ?? "output");

    const spec: Structure = JSON.parse(fs.readFileSync(specification, "utf-8")) as Structure;
    fs.mkdirSync(output, { recursive: true });

    const index: string = path.join(output, "index.ts");
    const project: Project = new Project({});

    const source: SourceFile = project.createSourceFile(index, fs.readFileSync(boilerplate, "utf-8"), {
        overwrite: true,
    });

    const baseOptionsType = source.getTypeAlias("BaseOptions");

    if (!baseOptionsType) {
        throw new Error("Boilerplate must define a `BaseOptions` type.");
    }

    const container: ClassDeclaration | undefined = source.getClass("API");

    if (!container) {
        throw new Error("Boilerplate must define an `API` class.");
    }

    generateOptionsTypes(spec, source);
    generateCommands(spec, container, 'ReturnType<API["__run"]>');
    project.saveSync();
})();

/**
 * Every command and menu may add some flags to the pool of available flags.
 * This means that, as we descend the command tree, we need to collect all the
 * flags that have been defined and add them to an options object.
 * Flags with omit: true in the spec are excluded from the options type.

View on GitHub (pinned to 793f7b2e16)