microsoft/TypeScript · error · TypeError

DeprecationError: '${name}' has been deprecated since v${sin

Error message

DeprecationError: '${name}' has been deprecated since v${since} and can no longer be used.

What it means

Thrown by the `createErrorDeprecation` factory in `src/deprecatedCompat/deprecate.ts` for APIs marked with `error: true`. Unlike warning deprecations (which only log once), error deprecations throw a `TypeError` on every call, with a message naming the API, the deprecation `since` version, and any custom message. It is the hard-removal gate for APIs that have aged out of the supported window.

Source

Thrown at src/deprecatedCompat/deprecate.ts:34

let typeScriptVersion: Version | undefined;

function getTypeScriptVersion() {
    return typeScriptVersion ?? (typeScriptVersion = new Version(version));
}

function formatDeprecationMessage(name: string, error: boolean | undefined, errorAfter: Version | undefined, since: Version | undefined, message: string | undefined) {
    let deprecationMessage = error ? "DeprecationError: " : "DeprecationWarning: ";
    deprecationMessage += `'${name}' `;
    deprecationMessage += since ? `has been deprecated since v${since}` : "is deprecated";
    deprecationMessage += error ? " and can no longer be used." : errorAfter ? ` and will no longer be usable after v${errorAfter}.` : ".";
    deprecationMessage += message ? ` ${formatStringFromArgs(message, [name])}` : "";
    return deprecationMessage;
}

function createErrorDeprecation(name: string, errorAfter: Version | undefined, since: Version | undefined, message: string | undefined) {
    const deprecationMessage = formatDeprecationMessage(name, /*error*/ true, errorAfter, since, message);
    return () => {
        throw new TypeError(deprecationMessage);
    };
}

function createWarningDeprecation(name: string, errorAfter: Version | undefined, since: Version | undefined, message: string | undefined) {
    let hasWrittenDeprecation = false;
    return () => {
        if (enableDeprecationWarnings && !hasWrittenDeprecation) {
            Debug.log.warn(formatDeprecationMessage(name, /*error*/ false, errorAfter, since, message));
            hasWrittenDeprecation = true;
        }
    };
}

export function createDeprecation(name: string, options: DeprecationOptions & { error: true; }): () => never;
export function createDeprecation(name: string, options?: DeprecationOptions): () => void;
export function createDeprecation(name: string, options: DeprecationOptions = {}) {
    const version = typeof options.typeScriptVersion === "string" ? new Version(options.typeScriptVersion) : options.typeScriptVersion ?? getTypeScriptVersion();
    const errorAfter = typeof options.errorAfter === "string" ? new Version(options.errorAfter) : options.errorAfter;

View on GitHub (pinned to b465fdbfe1)

Solutions

1. Migrate off the deprecated API to its documented replacement (the deprecation `message` usually names it).
2. If a migration path is incomplete, pin to the last TypeScript version where the API was a warning rather than an error.
3. Search the codebase for the deprecated `name` and replace all call sites.
4. Consult the release notes for the version cited in `since`.

Example fix

// before
const r = ts.someRemovedApi(args);   // throws DeprecationError
// after
const r = ts.replacementApi(args);     // per the deprecation message / release notes

// Before upgrading, grep for deprecated usages flagged by the previous (warning) version:
//   rg -n "someRemovedApi" src/
// and migrate each call site listed.

try {
  ts.someRemovedApi(args);
} catch (e) {
  if (e instanceof TypeError && /DeprecationError/.test(String(e))) {
    // migrate to the replacement; do not silently swallow
  } else throw e;
}

When it happens

Trigger: Calling a `deprecatedCompat` API whose deprecation entry has `error: true` (fully removed). The factory replaces the exported function with a thunk that always throws. Reached by importing and invoking any such API (e.g. removed legacy compiler options/APIs).

Common situations: Upgrading TypeScript to a version that hard-removes an API you were still using; relying on `@knipignore`-marked legacy surfaces; tooling pinning to old behavior that has now been gated out.

Related errors

• Invalid arguments
• You need to change the source code of fourslash test to use

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