microsoft/TypeScript · error · Error

Unknown compiler option '${name}'.

Error message

Unknown compiler option '${name}'.

What it means

Thrown by setCompilerOptionsFromHarnessSetting when a setting key is not a recognised compiler option (getCommandLineOption returns falsy) and is not the reserved 'typeScriptVersion' key. The harness validates every key against optionDeclarations and rejects anything unknown to prevent silent typos in test configuration.

Source

Thrown at src/harness/harnessIO.ts:298

        for (const name in settings) {
            if (ts.hasProperty(settings, name)) {
                const value = settings[name];
                if (value === undefined) {
                    throw new Error(`Cannot have undefined value for compiler option '${name}'.`);
                }
                if (name === "typeScriptVersion") {
                    continue;
                }
                const option = getCommandLineOption(name);
                if (option) {
                    const errors: ts.Diagnostic[] = [];
                    options[option.name] = optionValue(option, value, errors);
                    if (errors.length > 0) {
                        throw new Error(`Unknown value '${value}' for compiler option '${name}'.`);
                    }
                }
                else {
                    throw new Error(`Unknown compiler option '${name}'.`);
                }
            }
        }
    }

    function optionValue(option: ts.CommandLineOption, value: string, errors: ts.Diagnostic[]): any {
        switch (option.type) {
            case "boolean":
                return value.toLowerCase() === "true";
            case "string":
                return value;
            case "number": {
                const numverValue = parseInt(value, 10);
                if (isNaN(numverValue)) {
                    throw new Error(`Value must be a number, got: ${JSON.stringify(value)}`);
                }
                return numverValue;
            }

View on GitHub (pinned to b465fdbfe1)

Solutions

1. Check the spelling against the canonical compiler option list (ts.optionDeclarations) and correct it.
2. If the option was renamed, update to the current name.
3. Remove the key if it is not a real compiler option (move project-specific flags to a separate config mechanism).

Example fix

// before
// @stricNullChecks: true
// after
// @strictNullChecks: true

function validateOptionName(name: string, known: ReadonlySet<string>) {
    if (!known.has(name.toLowerCase())) {
        throw new Error(`'${name}' is not a known compiler option`);
    }
}

When it happens

Trigger: A test configuration contains a key that does not match any ts.CommandLineOption name (case-insensitive), e.g. a misspelled option or a removed/experimental flag not registered in the option declarations.

Common situations: Typo in the option name, using a project-specific flag that is not a tsc option, or referencing an option that was renamed/removed in the current compiler revision.

Related errors

• Cannot have undefined value for compiler option '${name}'.
• Unknown value '${value}' for compiler option '${name}'.
• Value must be a number, got: ${JSON.stringify(value)}
• Could not resolve JS module '${moduleName}' starting at '${i
• ${option.name} is a string value; tsconfig JSON must be pars

AI-assisted analysis of microsoft/TypeScript@b465fdbfe1 (2026-08-12). Data as JSON: /api/errors/79daa461dded4a68. Report an issue: GitHub.