EC
ERR_PACKAGE_IMPORT_NOT_EXPORTED
Node.jsERRORNotableModuleHIGH confidence

Package subpath is not defined in package.json "imports"

Production Risk

Module fails to load entirely; missing imports map entries cause startup crashes.

What this means

Thrown when an ES module uses a package self-referencing import (starting with #) that is not defined in the packages own "imports" field in package.json. The "imports" field is the internal equivalent of "exports" and must explicitly map every internal alias used.

Why it happens
  1. 1Using an #alias that is not declared in the package.json "imports" field
  2. 2A typo in the import specifier or the imports map key
  3. 3Forgetting to add a new internal alias after refactoring
How to reproduce

Triggered when a module imports an internal package specifier (#something) not listed in "imports".

trigger — this will error
trigger — this will error
// src/app.mjs
import { db } from '#database'; // not in package.json "imports"

expected output

Error [ERR_PACKAGE_IMPORT_NOT_EXPORTED]: Package import specifier "#database" is not defined in package.json

Fix

Add the missing specifier to the "imports" field

WHEN When you control the package

Add the missing specifier to the "imports" field
// package.json
{
  "imports": {
    "#database": "./src/db/index.js",
    "#utils": "./src/utils/index.js"
  }
}

Why this works

Declaring the alias in "imports" lets the ESM loader resolve the internal specifier to a real path.

Code examples
Triggerjs
// src/app.mjs
import { db } from '#database'; // not in package.json "imports"  // this triggers ERR_PACKAGE_IMPORT_NOT_EXPORTED
Handle in try/catchjs
try {
  // operation that may throw ERR_PACKAGE_IMPORT_NOT_EXPORTED
  riskyOperation()
} catch (err) {
  if (err.code === 'ERR_PACKAGE_IMPORT_NOT_EXPORTED') {
    console.error('ERR_PACKAGE_IMPORT_NOT_EXPORTED:', err.message)
  } else {
    throw err
  }
}
Defensive pattern to avoid itjs
// Validate inputs before calling the operation
function safe_err_package_import_not_exported(...args) {
  // validate args here
  return performOperation(...args)
}
What not to do

✕ Use # aliases without declaring them in package.json

The ESM loader has no way to resolve undeclared aliases.

Same error in other languages
ImportErrorin Python→
Sources
Official documentation ↗

Node.js Error Codes Documentation

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All Node.js errors