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
- Add (or restore) an exported `export type BaseOptions = { ... };` type alias to the boilerplate source file
- Check that the name is exactly `BaseOptions` (case-sensitive) and declared at the top level of the file
- 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
- Add a unit test asserting the boilerplate exports `BaseOptions` before generation runs
- Mark the `BaseOptions` declaration with a lint exemption comment so cleanup passes don't remove it
- Keep boilerplate template changes code-reviewed with the generator in mind
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
- Boilerplate must define an `API` class.
- Unknown type:
- a stack named already exists
- bind provider schema
- boilerplate directory
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)