{"record":{"id":"120bf821ac58e871","repo":"oxc-project/oxc","slug":"ambient-modules-cannot-be-nested-in-other-modules","errorCode":null,"errorMessage":"Ambient modules cannot be nested in other modules or namespaces.","messagePattern":"Ambient modules cannot be nested in other modules or namespaces\\.","errorType":"validation","errorClass":"OxcDiagnostic","httpStatus":null,"severity":"warning","filePath":"crates/oxc_transformer/src/typescript/diagnostics.rs","lineNumber":25,"sourceCode":"        .with_help(\n            \"Consider using 'import * as ns from \\\"mod\\\"',\n         'import {a} from \\\"mod\\\"', 'import d from \\\"mod\\\"', or another module format instead.\",\n        )\n        .with_label(span)\n        .with_error_code(\"TS\", \"1202\")\n}\n\n#[cold]\npub fn export_assignment_cannot_bed_used_in_esm(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"Export assignment cannot be used when targeting ECMAScript modules.\")\n        .with_help(\"Consider using 'export default' or another module format instead.\")\n        .with_label(span)\n        .with_error_code(\"TS\", \"1203\")\n}\n\n#[cold]\npub fn ambient_module_nested(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"Ambient modules cannot be nested in other modules or namespaces.\")\n        .with_label(span)\n}\n\n#[cold]\npub fn namespace_exporting_non_const(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"Namespaces exporting non-const are not supported by Oxc. Change to const or see: https://oxc.rs/docs/guide/usage/transformer/typescript.html#partial-namespace-support\")\n        .with_label(span)\n}\n\n#[cold]\npub fn namespace_not_supported(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"Namespace not marked type-only declare are disabled. To enable and review caveats see: https://oxc.rs/docs/guide/usage/transformer/typescript.html#partial-namespace-support\")\n        .with_label(span)\n}\n","sourceCodeStart":7,"sourceCodeEnd":40,"githubUrl":"https://github.com/oxc-project/oxc/blob/e1e7af627c8843ab64044ed466b128fcc21a035b/crates/oxc_transformer/src/typescript/diagnostics.rs#L7-L40","documentation":"Oxc's TypeScript namespace transform reports this when a module-string declaration (`declare module \"...\" {}` / TSExternalModuleDeclaration) is encountered where it is only legal at top level but appears nested inside a namespace body being flattened. During `handle_nested` (crates/oxc_transformer/src/typescript/namespace.rs:119-286), any `Declaration::TSExternalModuleDeclaration` found in the namespace body is routed to `handle_external` (namespace.rs:266-268), which errors when the declaration is not marked `declare` (namespace.rs:112-115). It mirrors TypeScript's TS2664 'Ambient modules cannot be nested in other modules or namespaces'.","triggerScenarios":"Transforming TypeScript where a `module \"name\" { ... }` / `declare module \"name\"` block sits inside `namespace Foo { ... }` or `module Foo { ... }` while namespaces are enabled (`allowNamespaces: true`, the default), and the nested external-module declaration lacks the `declare` modifier. Also fires for a top-level non-`declare` TSExternalModuleDeclaration passing through `enter_program`'s handle_external call (namespace.rs:47-52).","commonSituations":"Hand-written ambient typings pasted inside utility namespaces; refactoring a `.d.ts` that declared module augmentations (`declare module \"lib\"`) into a wrapped namespace for organization; generated typings from older tooling that nested module declarations; merging several declaration files where an `export declare module` ended up inside a wrapping namespace.","solutions":["Move the `declare module \"...\" { ... }` block out to the top level of the file","Ensure the nested declaration is truly ambient by marking it `declare module \"...\"` (declarations with `declare` do not trip the check in handle_external)","If the nesting was accidental (bad merge or copy-paste), delete the stray inner module declaration","For augmentation inside namespaces, split the file: keep the namespace in one file and the module augmentation at top level of another"],"exampleFix":"// before\nnamespace Config {\n  declare module \"json-schema\" {\n    interface Schema { id: string }\n  }\n}\n\n// after\nnamespace Config { /* ... */ }\n\ndeclare module \"json-schema\" {\n  interface Schema { id: string }\n}","handlingStrategy":"validation","validationCode":"// Reject nested ambient modules before transform (grounded: fires only for non-declare nested TSExternalModuleDeclaration)\nfunction hasNestedAmbientModule(src: string): boolean {\n  // heuristic: a `declare module \"...\"`/`module \"...\"` block indented inside namespace/module braces\n  return /(?:^|\\n)\\s{2,}(declare\\s+)?module\\s+[\"'][^\"']+[\"']\\s*\\{/.test(src);\n}","typeGuard":"// For programmatically built .d.ts content, validate structure before writing\nfunction isValidAugmentationPlacement(decl: { kind: 'module'; parent: string | null; hasDeclare: boolean }) {\n  if (decl.kind === 'module' && decl.parent !== null && !decl.hasDeclare) {\n    throw new Error('ambient module declarations must be top-level (TS2664)');\n  }\n  return true;\n}","tryCatchPattern":null,"preventionTips":["Keep `declare module \"...\"` augmentations at the top level of a dedicated typings file, never inside namespaces","When merging declaration files, flatten rather than wrap: one file per concern instead of a namespace umbrella","Prefer module augmentation via top-level `declare module` in a `.d.ts` included by tsconfig, so tsc itself (TS2664) also guards the same rule"],"tags":["oxc","typescript","transformer","ambient-modules","declaration-files","ts2664"],"backgroundTag":"typescript-ambient-module-misuse","analyzedSha":"e1e7af627c8843ab64044ed466b128fcc21a035b","analyzedAt":"2026-08-20T07:01:07.079Z","contentChangedAt":"2026-08-20T07:01:07.079Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}