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

This error occurs when a Next.js environment variable is undefined because it is missing the NEXT_PUBLIC_ prefix for client-side access, or the .env file is not loaded. Server-side env vars are not bundled into client code. Fix it by adding the NEXT_PUBLIC_ prefix or moving the logic to a server component or API route.

Reading the Stack Trace

Here's what each line means:

• at ApiClient (webpack-internal:///./src/lib/api.ts:5:42): The API client at line 5 tries to read process.env.NEXT_PUBLIC_API_URL but it is undefined in the client bundle.
• at fetchUsers (webpack-internal:///./src/hooks/useUsers.ts:8:23): The useUsers hook calls the API client, passing the undefined URL through the call chain.
• at renderWithHooks (node_modules/react-dom/cjs/react-dom.development.js:16305:18): React is rendering the component with hooks when the undefined variable causes the crash.

Common Causes

// .env.local
API_URL=https://api.example.com

// src/lib/api.ts
const baseUrl = process.env.API_URL; // undefined on client

// .env is in src/.env instead of project root
// src/.env
NEXT_PUBLIC_API_URL=https://api.example.com

// .env.local (just added)
NEXT_PUBLIC_API_URL=https://api.example.com
// Developer forgot to restart next dev

The Fix

Rename the environment variable with the NEXT_PUBLIC_ prefix so Next.js inlines it into the client bundle at build time. Add a runtime check that throws a descriptive error if the variable is missing, making misconfiguration easier to diagnose.

// .env.local
API_URL=https://api.example.com

// src/lib/api.ts
const baseUrl = process.env.API_URL;

export async function fetchUsers() {
  const res = await fetch(`${baseUrl}/users`);
  return res.json();
}

// .env.local
NEXT_PUBLIC_API_URL=https://api.example.com

// src/lib/api.ts
const baseUrl = process.env.NEXT_PUBLIC_API_URL;

if (!baseUrl) {
  throw new Error('NEXT_PUBLIC_API_URL environment variable is not set');
}

export async function fetchUsers() {
  const res = await fetch(`${baseUrl}/users`);
  return res.json();
}

Testing the Fix

import { fetchUsers } from '@/lib/api';

describe('fetchUsers', () => {
  const originalEnv = process.env;

  beforeEach(() => {
    process.env = { ...originalEnv, NEXT_PUBLIC_API_URL: 'https://api.example.com' };
  });

  afterEach(() => {
    process.env = originalEnv;
  });

  it('fetches users from the configured API URL', async () => {
    global.fetch = jest.fn().mockResolvedValue({
      json: () => Promise.resolve([{ id: 1, name: 'Alice' }]),
    });
    const users = await fetchUsers();
    expect(fetch).toHaveBeenCalledWith('https://api.example.com/users');
    expect(users).toHaveLength(1);
  });

  it('throws if NEXT_PUBLIC_API_URL is not set', () => {
    delete process.env.NEXT_PUBLIC_API_URL;
    expect(() => require('@/lib/api')).toThrow('NEXT_PUBLIC_API_URL');
  });
});

Run your tests:

npm test

Pushing Through CI/CD

git checkout -b fix/env-variable-prefix,git add .env.local src/lib/api.ts src/lib/__tests__/api.test.ts,git commit -m "fix: add NEXT_PUBLIC_ prefix to client-side env variable",git push origin fix/env-variable-prefix

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    env:
      NEXT_PUBLIC_API_URL: https://api.example.com
    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. Rename the environment variable in .env.local with the NEXT_PUBLIC_ prefix.
2. Restart the development server to load the new variable.
3. Open a pull request with the env variable and code changes.
4. Wait for CI checks to pass on the PR.
5. Merge to main and verify the variable is set in the deployment environment.

Frequently Asked Questions