Skip to Content
Troubleshooting

Last Updated: 3/9/2026

Troubleshooting

Common issues and solutions when using Nano ID.

Installation Issues

”Cannot find module ‘nanoid’”

Symptoms:

Error: Cannot find module 'nanoid'

Solutions:

  1. Install the package:

    npm install nanoid

  2. Check package.json:

    {
  "dependencies": {
    "nanoid": "^5.0.0"
  }
}

  3. Clear cache and reinstall:

    rm -rf node_modules package-lock.json
npm install

“require() of ES Module not supported”

Symptoms:

Error [ERR_REQUIRE_ESM]: require() of ES Module
/node_modules/nanoid/index.js not supported

Cause: Trying to require() an ESM package.

Solutions:

  1. Use dynamic import (Node.js 18+):

    let nanoid
 
async function getId() {
  if (!nanoid) {
    ({ nanoid } = await import('nanoid'))
  }
  return nanoid()
}

  2. Use Node.js 22.12+ with native support:

    const { nanoid } = require('nanoid') // Works in 22.12+

  3. Use Node.js 20 with flag:

    node --experimental-require-module script.js

  4. Downgrade to Nano ID 3.x:

    npm install nanoid@3

  5. Convert to ESM:

    // package.json
{
  "type": "module"
}
    // script.js
import { nanoid } from 'nanoid'

TypeScript Issues

”Cannot find module ‘nanoid’ or its type declarations”

Symptoms:

TS2307: Cannot find module 'nanoid' or its corresponding type declarations.

Solutions:

  1. Install package:

    npm install nanoid

  2. Update tsconfig.json:

    {
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true
  }
}

  3. For Node16 resolution:

    {
  "compilerOptions": {
    "module": "Node16",
    "moduleResolution": "node16"
  }
}

“Module ‘“nanoid”’ has no exported member ‘nanoid’”

Symptoms:

TS2305: Module '"nanoid"' has no exported member 'nanoid'

Cause: Incorrect import syntax.

Solution:

// ❌ Wrong
import nanoid from 'nanoid'
 
// ✅ Correct
import { nanoid } from 'nanoid'

React Issues

IDs Change on Every Render

Symptoms: Component re-renders completely, losing state.

Cause: Generating ID in render function.

Solution:

import { nanoid } from 'nanoid'
import { useMemo } from 'react'
 
// ❌ Wrong
function Component() {
  const id = nanoid() // New ID every render!
  return <div id={id}>Content</div>
}
 
// ✅ Correct
function Component() {
  const id = useMemo(() => nanoid(), []) // Generate once
  return <div id={id}>Content</div>
}

“crypto.getRandomValues is not a function”

Symptoms (React Native):

TypeError: crypto.getRandomValues is not a function

Cause: Missing polyfill in React Native.

Solution:

npm install react-native-get-random-values
// MUST be imported BEFORE nanoid
import 'react-native-get-random-values'
import { nanoid } from 'nanoid'

Browser Issues

”crypto is not defined”

Symptoms:

ReferenceError: crypto is not defined

Cause: Very old browser or non-HTTPS context.

Solutions:

  1. Use HTTPS: crypto only available on HTTPS (or localhost)

  2. Use non-secure variant:

    import { nanoid } from 'nanoid/non-secure'

  3. Check browser support: Chrome 11+, Firefox 21+, Safari 6.1+

Bundle Size Too Large

Symptoms: Nano ID adds unexpected size to bundle.

Cause: Bundler not tree-shaking correctly.

Solutions:

  1. Use named imports:

    // ✅ Good: Tree-shakeable
import { nanoid } from 'nanoid'
 
// ❌ Bad: Imports everything
import * as Nanoid from 'nanoid'

  2. Check bundler config (Webpack):

    module.exports = {
  optimization: {
    usedExports: true,
    sideEffects: false
  }
}

  3. Use non-secure for smaller size:

    import { nanoid } from 'nanoid/non-secure' // 90 bytes vs 118 bytes

Performance Issues

Slow ID Generation

Symptoms: Generating IDs takes >1ms.

Cause: Recreating custom alphabet generator.

Solution:

import { customAlphabet } from 'nanoid'
 
// ❌ Wrong: Creates generator every time
for (let i = 0; i < 1000; i++) {
  const nanoid = customAlphabet('0123456789', 10)
  const id = nanoid() // Slow!
}
 
// ✅ Correct: Create once, use many times
const nanoid = customAlphabet('0123456789', 10)
for (let i = 0; i < 1000; i++) {
  const id = nanoid() // Fast!
}

High Memory Usage

Symptoms: Memory grows when generating many IDs.

Cause: Not a Nano ID issue (IDs are just strings).

Solution: Check if storing IDs unnecessarily:

// ❌ Bad: Storing all IDs in memory
const ids = []
for (let i = 0; i < 1000000; i++) {
  ids.push(nanoid())
}
 
// ✅ Good: Process and discard
for (let i = 0; i < 1000000; i++) {
  const id = nanoid()
  await db.insert({ id, data: '...' })
  // ID discarded after insert
}

Collision Issues

Getting Duplicate IDs

Symptoms: Database reports duplicate key errors.

Causes & Solutions:

  1. ID too short:

    // ❌ Bad: Only 36 bits of entropy
const id = nanoid(6) // High collision risk!
 
// ✅ Good: 126 bits of entropy
const id = nanoid() // Default 21 chars

  2. Using non-secure in production:

    // ❌ Bad: Predictable
import { nanoid } from 'nanoid/non-secure'
 
// ✅ Good: Cryptographically secure
import { nanoid } from 'nanoid'

  3. Clock skew in distributed systems:

    • Not a Nano ID issue (IDs are random, not time-based)
    • Check if using time-based IDs elsewhere

  4. Add collision detection:

    async function createUniqueId(maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const id = nanoid()
    const exists = await db.exists(id)
    if (!exists) return id
  }
  throw new Error('Failed to generate unique ID')
}

Testing Issues

Unpredictable Tests

Symptoms: Tests fail randomly due to different IDs.

Solution: Mock Nano ID:

// __mocks__/nanoid.js
let counter = 0
export const nanoid = () => `test-id-${counter++}`
 
// test.js
jest.mock('nanoid')
 
import { nanoid } from 'nanoid'
 
test('creates user', () => {
  const id = nanoid() // "test-id-0"
  expect(id).toBe('test-id-0')
})

Snapshot Tests Failing

Symptoms: Snapshots differ due to random IDs.

Solution: Mock or use deterministic IDs in tests:

import { customRandom } from 'nanoid'
 
// Deterministic ID for tests
let seed = 0
const testNanoid = customRandom('abcdef', 10, (size) => {
  return new Uint8Array(size).map(() => (seed++) % 256)
})
 
test('renders component', () => {
  seed = 0 // Reset seed
  const id = testNanoid() // Always same ID
  expect(component).toMatchSnapshot()
})

Getting Help

Check Documentation

  1. Installation
  2. Quick Start
  3. API Reference
  4. Platform Guides

Search Issues

Search GitHub Issues  for similar problems.

Report Bug

  1. Check if issue exists
  2. Create minimal reproduction
  3. Open new issue 

Security Issues

Report security vulnerabilities to Tidelift .

See Also

Database IntegrationMigration Guide