tailwindlabs/heroicons · error · Error

You're trying to import `@heroicons/react/outline/${property

Error message

You're trying to import `@heroicons/react/outline/${property}` from Heroicons v1 but have installed Heroicons v2. Install `@heroicons/react@v1` to resolve this error.

What it means

In Heroicons v1, icons lived at `@heroicons/react/outline/<Icon>` and `@heroicons/react/solid/<Icon>`. In v2 these paths are compatibility shims implemented as throwing Proxies. Accessing any icon through `@heroicons/react/outline` means the code still uses the v1 import layout while the installed package is v2.

Source

Thrown at react/outline/index.js:9

let proxy = new Proxy(
  {},
  {
    get: (obj, property) => {
      if (property === '__esModule') {
        return {}
      }

      throw new Error(
        `You\'re trying to import \`@heroicons/react/outline/${property}\` from Heroicons v1 but have installed Heroicons v2. Install \`@heroicons/react@v1\` to resolve this error.`
      )
    },
  }
)

module.exports = proxy

View on GitHub (pinned to 616b7a4dbb)

Solutions

Rewrite the import to a v2 subpath: `import { BeakerIcon } from '@heroicons/react/24/outline'`.
Alternatively pin v1 if the codebase depends on v1 layout and API: `npm install @heroicons/react@v1`.
Run a find/replace for `@heroicons/react/outline/<Name>` and `@heroicons/react/solid/<Name>` imports across the repo.
Check transitive dependencies or shared UI libraries that still emit v1-style import paths and upgrade them.

Example fix

// before
import BeakerIcon from '@heroicons/react/outline/BeakerIcon'

// after
import { BeakerIcon } from '@heroicons/react/24/outline'

Defensive patterns

Strategy: validation

Validate before calling

// detect v1-style imports before build
const pkg = require('@heroicons/react/package.json')
if (pkg.version.startsWith('2.') && process.env.HEROICONS_V1_IMPORTS === '1') {
  throw new Error('Codebase still uses @heroicons/react/outline/<Icon> v1 imports with heroicons v2 installed')
}

Prevention

Pin the heroicons major version in package.json (e.g. '^2.0.0') and commit the lockfile.
Run a find/replace or codemod for '/outline/<Icon>' imports when upgrading to v2.
Add a CI grep step that fails on '@heroicons/react/outline/' import paths under v2.
Update internal UI libraries that emit v1-style import paths.

When it happens

Trigger: Any import such as `import BeakerIcon from '@heroicons/react/outline/BeakerIcon'` or `require('@heroicons/react/outline/BeakerIcon')` against heroicons v2. The `outline/index.js` Proxy get trap throws with the interpolated icon name (`${property}`).

Common situations: Following v1 documentation or tutorials after `npm install @heroicons/react` installed v2; dependency upgrades (semver-major mismatch not noticed); code generators or design-system wrappers hardcoding `outline/` paths; stale lockfiles partially upgraded.

Related errors

AI-assisted analysis of tailwindlabs/heroicons@616b7a4dbb (2026-08-31). Data as JSON: /api/errors/b1389424c2cfd445. Report an issue: GitHub.