Fix TypeError: Cannot read properties of undefined (reading 'map') in Next.js

This error occurs when you call .map() on a variable that is undefined, typically because an API response hasn't loaded yet or returned an unexpected shape. Fix it by adding a guard clause, optional chaining, or providing a default empty array before calling .map() on the data.

Reading the Stack Trace

Here's what each line means:

• at UserList (webpack-internal:///./src/components/UserList.tsx:14:22): The error originates at line 14 of UserList.tsx where .map() is called on an undefined variable.
• at renderWithHooks (node_modules/react-dom/cjs/react-dom.development.js:16305:18): React's hook rendering pipeline is executing when the component tries to render.
• at mountIndeterminateComponent (node_modules/react-dom/cjs/react-dom.development.js:20069:13): The component is being mounted for the first time, meaning initial data may not be available yet.

Common Causes

export default function UserList({ data }) {
  return (
    <ul>
      {data.users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

const res = await fetch('/api/users');
const data = await res.json();
// API returns { results: [...] } not { users: [...] }
return data.users.map(u => u.name);

function UserList({ users }) {
  return users.map(u => <li key={u.id}>{u.name}</li>);
}

The Fix

Add a guard clause that checks whether data and data.users exist before attempting to call .map(). This prevents the TypeError by rendering a loading state when the data is not yet available.

export default function UserList({ data }) {
  return (
    <ul>
      {data.users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

export default function UserList({ data }) {
  if (!data?.users) {
    return <p>Loading...</p>;
  }

  return (
    <ul>
      {data.users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

Testing the Fix

import { render, screen } from '@testing-library/react';
import UserList from './UserList';

describe('UserList', () => {
  it('renders loading state when data is undefined', () => {
    render(<UserList data={undefined} />);
    expect(screen.getByText('Loading...')).toBeInTheDocument();
  });

  it('renders loading state when data.users is undefined', () => {
    render(<UserList data={{}} />);
    expect(screen.getByText('Loading...')).toBeInTheDocument();
  });

  it('renders user list when data is available', () => {
    const data = { users: [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }] };
    render(<UserList data={data} />);
    expect(screen.getByText('Alice')).toBeInTheDocument();
    expect(screen.getByText('Bob')).toBeInTheDocument();
  });
});

Run your tests:

npm test

Pushing Through CI/CD

git checkout -b fix/typeerror-map-undefined,git add src/components/UserList.tsx src/components/__tests__/UserList.test.tsx,git commit -m "fix: guard against undefined data before calling .map()",git push origin fix/typeerror-map-undefined

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test -- --coverage
      - run: npm run build

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

npm install bugstack-sdk

import { initBugStack } from 'bugstack-sdk'

initBugStack({ apiKey: process.env.BUGSTACK_API_KEY })

Deploying the Fix (Manual Path)

1. Run the full test suite locally to confirm the fix passes.
2. Open a pull request with the guard clause changes.
3. Wait for CI checks to pass on the PR.
4. Have a teammate review and approve the PR.
5. Merge to main and verify the deployment in staging before promoting to production.

Frequently Asked Questions