How to fix Ambient declaration 'X' cannot be declared in a non-ambient context in TypeScript

What this error means

This error indicates that TypeScript encountered an ambient declaration in a context where implementations are required. Ambient declarations are type-only declarations made with the `declare` keyword. They exist purely for the type system at compile-time and don't generate any JavaScript code. According to TypeScript's type system rules, ambient declarations can only appear in: 1. **Declaration files (.d.ts files)** - Files dedicated to type definitions 2. **Declare namespace blocks** - Inside `declare namespace { }` or `declare module { }` blocks 3. **Global scope of .d.ts files** - Top-level declarations When you use `declare` in a regular .ts file (which is a "non-ambient context" because it contains actual implementations), TypeScript throws this error because it doesn't know how to reconcile type-only declarations with executable code.

Typical symptoms

• TypeScript compiler error mentioning 'ambient declaration' and 'non-ambient context'
• Error appears when using 'declare' keyword in regular .ts files
• VS Code shows red squiggles under declare statements
• Build fails during compilation with error TS1039 or similar
• Error mentions specific identifiers that cannot be declared
• IDE cannot identify the declared types even though syntax looks correct
• Moving code between .ts and .d.ts files causes different error behavior

Common causes

1. Using the 'declare' keyword in a .ts file instead of a .d.ts declaration file
2. Trying to use 'declare' outside of a declare namespace or declare module block in .ts files
3. Mixing ambient declarations with executable code in the same file
4. Type definitions placed in implementation files rather than declaration files
5. Incorrect file extension - .ts instead of .d.ts for pure type definitions
6. Misunderstanding the purpose of declare keyword - it's only for types, not values

How to fix "Ambient declaration 'X' cannot be declared in a non-ambient context"

// ❌ WRONG - in a regular .ts file
declare namespace MyNamespace {
  interface MyInterface {
    name: string;
  }
}

export function doSomething() {
  // implementation
}

// ✅ CORRECT - in a .d.ts file
declare namespace MyNamespace {
  interface MyInterface {
    name: string;
  }

  function doSomething(): void;
}

src/
├── types/
│   └── my-namespace.d.ts      # Type definitions only
├── lib/
│   └── my-module.ts            # Implementation code
└── index.ts

declare namespace MyNamespace {
  interface User {
    id: string;
    name: string;
  }

  function getUserById(id: string): User | null;
}

namespace MyNamespace {
  export interface User {
    id: string;
    name: string;
  }

  export function getUserById(id: string): User | null {
    // implementation
    return null;
  }
}

export = MyNamespace;

// ✅ This is allowed - declare is inside a namespace block
declare namespace GlobalTypes {
  interface Window {
    customProperty: string;
  }
}

// ✅ This is allowed - augmenting module types
declare module 'express' {
  interface Request {
    userId?: string;
  }
}

// Implementation code can follow
export function setupMiddleware() {
  // ...
}

// ❌ WRONG
declare interface User {
  name: string;
}

// ✅ CORRECT - no declare keyword
interface User {
  name: string;
}

class UserClass implements User {
  name: string = '';
}

export { User, UserClass };

{
  "compilerOptions": {
    "declaration": true,
    "declarationDir": "./dist/types",
    "outDir": "./dist",
    "rootDir": "./src",
    "typeRoots": ["./node_modules/@types", "./src/types"],
    "skipLibCheck": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Advanced notes

// ✅ In a .d.ts file or at top-level
declare global {
  var globalVar: string;
}

// ✅ In a .d.ts file
declare module 'some-library' {
  export interface SomeInterface {
    newProperty: string;
  }
}

// ✅ In a .d.ts file
declare module '*.json' {
  const content: Record<string, unknown>;
  export default content;
}

tsc --version

Frequently asked questions

What does "Ambient declaration 'X' cannot be declared in a non-ambient context" mean?

This error indicates that TypeScript encountered an ambient declaration in a context where implementations are required. Ambient declarations are type-only declarations made with the declare keyword. They exist purely for the type system at compile-time and don't generate any JavaScript code.

How do I fix "Ambient declaration 'X' cannot be declared in a non-ambient context"?

This error occurs when you try to use the 'declare' keyword in a regular .ts file instead of a .d.ts declaration file. Ambient declarations are type-only declarations that can only exist in .d.ts files or within declare namespace blocks.

What causes "Ambient declaration 'X' cannot be declared in a non-ambient context"?

Using the 'declare' keyword in a .ts file instead of a .d.ts declaration file Trying to use 'declare' outside of a declare namespace or declare module block in .ts files Mixing ambient declarations with executable code in the same file

Is the "Ambient declaration 'X' cannot be declared in a non-ambient context" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• Argument of type 'boolean' is not assignable to parameter of type 'string'

  How to fix "Argument of type 'boolean' is not assignable to parameter of type 'string'" in TypeScript

  MEDIUM

• Option 'allowJs' is not compatible with 'checkJs' when 'declaration' is enabled

  How to fix 'allowJs is not compatible with checkJs when declaration is enabled' in TypeScript

  MEDIUM

• Argument of type 'never' is not assignable to parameter of type 'any'

  How to fix 'Argument of type never is not assignable to parameter of type any' in TypeScript

  MEDIUM

• Option 'allowImportingTsExtensions' can only be used when either 'noEmit' or 'emitDeclarationOnly' is set.

  How to fix 'allowImportingTsExtensions requires noEmit to be enabled' in TypeScript

  LOW

• Cannot find name 'process'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node` and then add 'node' to the types field in your tsconfig.

  How to fix "Cannot find name 'process'" in TypeScript

  MEDIUM

• Module has no exported member 'X'

  How to fix 'Module has no exported member X' error in TypeScript

  MEDIUM

Official resources & further reading

• 📚TypeScript Official Documentation
• TypeScript: Documentation - Namespaces
• TypeScript: Documentation - Namespaces and Modules
• TutorialsPoint - TypeScript Ambients
• Medium - Guide to TypeScript Ambient Declarations
• TypeScript Deep Dive - Ambient Declarations
• GeeksforGeeks - TypeScript Ambients Declaration