How to fix Exported variable 'X' has or is using name 'Y' from external module 'Z' but cannot be named in TypeScript

What this error means

The TS4023 error appears when TypeScript is generating declaration files (enabled via `declaration: true` or `composite: true` in tsconfig.json) and encounters an exported variable that uses types from external modules in a way that cannot be properly represented in the generated .d.ts file. TypeScript needs to create a public type signature for every exported value. When you export a variable whose type is inferred from external module types, the compiler must decide how to express that type in the declaration file. If the type includes references to types that aren't explicitly imported or can't be publicly named, TypeScript cannot generate a valid declaration file. This error is fundamentally about the boundary between your module's public API and its internal implementation. TypeScript is warning you that consumers of your module won't be able to see accurate type information for this exported variable. Common scenarios include: 1. **Inferred types from re-exports**: Exporting objects or arrays that contain instances of classes from external modules 2. **Complex type inference**: TypeScript infers a type that includes private or non-exported types from dependencies 3. **Declaration file generation**: The error only appears when TypeScript tries to generate .d.ts files, not during regular compilation In TypeScript 2.9+, many cases are handled automatically using import type syntax in generated declarations, but complex scenarios still trigger this error.

Typical symptoms

• Compilation fails only when declaration: true is enabled in tsconfig.json
• Error message references TS4023 with specific variable and module names
• Error appears only during declaration file generation, not during regular builds
• Error mentions 'but cannot be named' at the end of the message
• Build succeeds when declaration option is disabled
• IDE may show error on exported const/let/var declarations
• Error occurs in library projects using composite: true for project references

Common causes

1. Exporting a variable with an inferred type that references unexported types from external modules
2. Re-exporting objects or classes from external modules without explicit type annotations
3. Using heavily inferred types that indirectly reference external module types
4. Exporting variables that contain instances of classes from dependencies
5. Type inference creates circular dependencies between modules in declaration files
6. Using generic types that resolve to external module types without explicit annotations
7. Exporting default objects that aggregate classes/types from multiple external modules

How to fix "Exported variable 'X' has or is using name 'Y' from external module 'Z' but cannot be named"

// BEFORE - Type is inferred, causes TS4023
import { DataGrid } from '@mui/x-data-grid';

export const myGrid = DataGrid({ /* config */ });
// Error: Exported variable 'myGrid' has or is using name 'DataGridComponent'

// AFTER - Explicitly typed
import { DataGrid, DataGridProps } from '@mui/x-data-grid';

export const myGrid: React.ComponentType<DataGridProps> = DataGrid({ /* config */ });

// BEFORE
import { someFunction } from 'external-lib';

export const config = {
  handler: someFunction(),
  options: { /* ... */ }
};

// AFTER
import { someFunction, HandlerType } from 'external-lib';

interface ConfigType {
  handler: HandlerType;
  options: { /* ... */ };
}

export const config: ConfigType = {
  handler: someFunction(),
  options: { /* ... */ }
};

// Error message says:
// "has or is using name 'NumberKeywords' from external module 'ajv/dist/types/json-schema'"

// BEFORE - Type used but not imported
import Ajv from 'ajv';

export const validator = new Ajv();

// AFTER - Import the type explicitly
import Ajv from 'ajv';
import type { NumberKeywords } from 'ajv/dist/types/json-schema';

export const validator = new Ajv();

import type { SomeType } from 'external-module';
import { someFunction } from 'external-module';

export const result: ReturnType<typeof someFunction> = someFunction();

// BEFORE - Re-exporting without types
export { default as MyComponent } from 'external-lib';

// AFTER - Explicit type export
export type { ComponentProps } from 'external-lib';
export { default as MyComponent } from 'external-lib';

// BEFORE
import * as Utils from './utils';
export const helpers = Utils;

// AFTER
export type * as Utils from './utils';
export * from './utils';

// OR with explicit namespace
import type * as UtilsType from './utils';
import * as UtilsImpl from './utils';

export const helpers: typeof UtilsType = UtilsImpl;

// external-lib/index.ts
// BEFORE - InternalConfig not exported
interface InternalConfig {
  setting: string;
}

export function createHandler(config: InternalConfig) {
  return { /* ... */ };
}

// AFTER - Export all types used in public API
export interface InternalConfig {
  setting: string;
}

export function createHandler(config: InternalConfig) {
  return { /* ... */ };
}

import { createHandler } from 'external-lib';
import type { InternalConfig } from 'external-lib';

export const handler: ReturnType<typeof createHandler> = createHandler({
  setting: 'value'
});

# Check your TypeScript version
npx tsc --version

# Update to latest TypeScript
npm install --save-dev typescript@latest

# Or specific version (5.x recommended)
npm install --save-dev typescript@^5.0.0

// Your source code
import { Hash } from 'crypto';
export const hash = createHash('sha256');

// Generated declaration (TypeScript 2.9+)
export declare const hash: import("crypto").Hash;

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "esnext",
    "moduleResolution": "bundler",
    "declaration": true
  }
}

// BEFORE
import { createComplexObject } from 'external-lib';

export const instance = createComplexObject({ /* config */ });

// AFTER - Using ReturnType
import { createComplexObject } from 'external-lib';

export const instance: ReturnType<typeof createComplexObject> =
  createComplexObject({ /* config */ });

// BEFORE
import { SomeClass } from 'external-lib';

export const instance = new SomeClass();

// AFTER - Using InstanceType
import { SomeClass } from 'external-lib';

export const instance: InstanceType<typeof SomeClass> = new SomeClass();

import { processData } from 'external-lib';

type ProcessedData = {
  result: string;
  metadata: Record<string, unknown>;
};

export const data: ProcessedData = processData(input);

Advanced notes

// tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "declarationMap": true
  }
}

{
  "compilerOptions": {
    "moduleDetection": "force"
  }
}

// types/module-augmentation.d.ts
import 'problematic-library';

declare module 'problematic-library' {
  export interface PublicConfig {
    // Add missing types
  }
}

// Instead of exporting library objects directly
import { ThirdPartyClass } from 'library';

// Create a typed wrapper
export interface MyWrapperConfig {
  // Your explicit config type
}

export function createWrapper(config: MyWrapperConfig) {
  return new ThirdPartyClass(config);
}

/// <reference types="dependency-package" />

export const value: DependencyType = createValue();

# Generate declarations and inspect
npx tsc --declaration --emitDeclarationOnly

# Check the .d.ts file
cat dist/index.d.ts

{
  "compilerOptions": {
    "declaration": false
  }
}

Frequently asked questions

What does "TS4023" mean?

ts file. TypeScript needs to create a public type signature for every exported value. When you export a variable whose type is inferred from external module types, the compiler must decide how to express that type in the declaration file.

How do I fix "TS4023"?

This TypeScript error (TS4023) occurs when generating declaration files and the compiler cannot properly reference types from external modules in your exported variables. It happens when you export a variable whose inferred type uses types from external modules that cannot be explicitly named in the generated .d.ts file.

What causes "TS4023"?

Exporting a variable with an inferred type that references unexported types from external modules Re-exporting objects or classes from external modules without explicit type annotations Using heavily inferred types that indirectly reference external module types

Is the "TS4023" error serious?

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

Related errors

• Cannot use expression in template literal type

  Cannot use expression in template literal type

  MEDIUM

• Export declaration conflicts with exported declaration of 'X'

  How to fix 'Export declaration conflicts with exported declaration of X' in TypeScript

  MEDIUM

• Expression is not assignable to 'never'

  How to fix 'Expression is not assignable to never' error in TypeScript

  MEDIUM

• Experimental support for decorators is a feature that is subject to change in a future release. Set the 'experimentalDecorators' option in your 'tsconfig' to remove this warning.

  How to fix 'experimentalDecorators option is not set' error in TypeScript

  MEDIUM

• 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 Issue #5711 - TS4023 Discussion(GitHub)
• 🐙
  TypeScript Issue #41934 - Exported variable cannot be named(GitHub)
• 📖
  TypeScript 2.9 Release Notes - Import Types(Official Docs)
• Jamis Charles - TS4023 Cannot Be Named Error
• 🐙
  TypeScript Issue #25188 - Type Inference with External Modules(GitHub)
• 📖
  TypeScript Handbook - Declaration Files(Official Docs)
• 📖
  TypeScript TSConfig - declaration Option(Official Docs)
• 🐙
  TypeScript Issue #9944 - External Module Naming(GitHub)