How to fix Type augmentation conflicts with existing declaration in TypeScript

TypeScriptINTERMEDIATEMEDIUMUpdated Dec 11, 2025· 112 views

TypeScript emits this error when a module or global augmentation tries to redeclare a symbol that already exists with a conflicting shape, typically while extending third-party type definitions or maintaining multiple .d.ts files.

Quick fix

Fixes Type augmentation conflicts with existing declaration

import "express"; // keeps this file as an external module

declare module "express-serve-static-core" {
  interface Request {
    requestId?: string;
  }
}
  1. Keep your augmentation in a module and import the target package
  2. Check the original definitions before adding new members
  3. Extend rather than override existing members
typescript — error
import "express"; // keeps this file as an external module
declare module "express-serve-static-core" {
  interface Request {
    requestId?: string;
  }
}
Type augmentation conflicts with existing declaration

What this error means

TypeScript transparently merges declarations with the same name, so augmentations are only safe when every file agrees on how a type looks. When the compiler sees two augmentations of the same symbol that disagree on optional/required members or types it already knows about, it raises "Type augmentation conflicts with existing declaration" and refuses to merge them. This usually happens in extension files that sit next to existing definitions from @types packages or that accidentally run in the global scope instead of the module scope required for deliberate merging. Keeping augmentations tightly aligned with the shipped declarations prevents the conflict and keeps the compiler happy.

Typical symptoms

  • tsc stops with 'Type augmentation conflicts with existing declaration' and points to the augmentation file.
  • IDE tooling underlines the augmentation and shows duplicate symbol warnings for module members.
  • The same interface or namespace is already defined in another declaration file, and the compiler complains as soon as you add a new property.
  • You can build in JavaScript but the TypeScript build fails because it treats the merged declarations as incompatible.
  • A custom global or module augmentation suddenly stopped compiling after upgrading a dependency or adding a new declaration file.

Common causes

  1. Two augmentation files or a shipped .d.ts plus your file declare the same property with incompatible types.
  2. You redefine an existing member instead of declaring a new optional property or method.
  3. The augmentation file is not a module (no imports/exports), so TypeScript tries to merge into the global namespace where the declaration already exists.
  4. tsconfig includes multiple type roots or you manually duplicated the ambient declaration, so multiple versions have the same module name.
  5. You created a module augmentation that overlaps with a namespaced export from the package's own declarations (different paths or casing confuse the merger).

How to fix "Type augmentation conflicts with existing declaration"

1Keep your augmentation in a module and import the target package

Start the file with an import so the compiler treats it as a module-level augmentation rather than a global script. This scope guarantees TypeScript merges your additions with the shipped declaration instead of generating a conflicting second declaration.

ts
import "express"; // keeps this file as an external module

declare module "express-serve-static-core" {
  interface Request {
    requestId?: string;
  }
}

If you omit the import, TypeScript will combine your file with the global scope and may see two declarations for the same interface, which triggers the conflict.

2Check the original definitions before adding new members

Open the package's .d.ts file inside node_modules/@types (or the package itself) before adding properties. Match the casing and optionality of existing members to avoid duplicate declarations with different names.

Use resolution tracing to confirm which file TypeScript loads for the module:

bash
npx tsc --traceResolution | grep "express.d.ts"

If the trace shows a different file than the one you edited, you are augmenting the wrong declaration and the compiler treats your work as a conflicting declaration on top of the shipped definition. Move your augmentation next to the file that actually defines the module or reference it directly via the /// <reference path="..."> directive when necessary.

3Extend rather than override existing members

When you need to change a property from the shipped declaration, declare only the new optional members or use helper types instead of repeating the property with a different type.

ts
type Overwrite<T, K extends keyof T, V> = Omit<T, K> & V;

declare module "express-serve-static-core" {
  interface Request extends Overwrite<Request, "user", { user: CustomUser }> {}
}

The compiler now merges your augmentation by replacing specific keys via Overwrite, so it never emits the conflicting property twice. If you must adjust an exported member's type, define a new property (e.g., customUser) and leave the original untouched, or introduce a new interface that extends the existing one instead of re-declaring it.

Frequently asked questions

What does "Type augmentation conflicts with existing declaration" mean?
TypeScript transparently merges declarations with the same name, so augmentations are only safe when every file agrees on how a type looks. When the compiler sees two augmentations of the same symbol that disagree on optional/required members or types it already knows about, it raises "Type augmentation conflicts with existing declaration" and refuses to merge them. This usually happens in extension files that sit next to existing definitions from @types packages or that accidentally run in the global scope instead of the module scope required for deliberate merging.
How do I fix "Type augmentation conflicts with existing declaration"?
TypeScript emits this error when a module or global augmentation tries to redeclare a symbol that already exists with a conflicting shape, typically while extending third-party type definitions or maintaining multiple .d.ts files.
What causes "Type augmentation conflicts with existing declaration"?
Two augmentation files or a shipped .d.ts plus your file declare the same property with incompatible types. You redefine an existing member instead of declaring a new optional property or method. The augmentation file is not a module (no imports/exports), so TypeScript tries to merge into the global namespace where the declaration already exists.
Is the "Type augmentation conflicts with existing declaration" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading