Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

AuthUserPoolException: Auth UserPool not configured in a Next.js app

ErrorAuthUserPoolException: Auth UserPool not configured.

Short answer

The error means an Amplify Auth call ran before Amplify.configure did. Configure Amplify in a client component rendered by the root layout, pass ssr true, and do not call Amplify APIs at module level in child files, where they run on import.

  • Applies to Next.js 15, aws-amplify v6, Amplify Gen 2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find where Amplify is configured and where Auth functions are called, and check which one runs first.

    grep -rn "Amplify.configure" --include="*.ts" --include="*.tsx" src app 2>/dev/null
    grep -rn "fetchAuthSession\|getCurrentUser" --include="*.ts" --include="*.tsx" src app 2>/dev/null
  2. 2Match what you see, then jump to its fix

    1. 1grep finds no Amplify.configure, or only in a file the page does not import.Amplify.configure is not in the app entryFix
    2. 2fetchAuthSession() or similar is called at the top of an imported file, outside a component.An Auth call runs at module level, before configurationFix
    3. 3The error appears in a Server Component, route handler or middleware.Server code calls Amplify without the server runnerFix

What does the error look like?

  • AuthUserPoolException: Auth UserPool not configured.
  • Auth UserPool not configured

Cause 1 of 3

Amplify.configure is not in the app entry

1Check

Configuration must run in the app's root, as early as possible, and in a multi-page setup each route needs it to run.

ls amplify_outputs.json

2Fix

Create a client component that configures Amplify with the generated outputs and ssr true, and render it in the root layout.

// components/ConfigureAmplifyClientSide.tsx
'use client';
import { Amplify } from 'aws-amplify';
import outputs from '../amplify_outputs.json';

Amplify.configure(outputs, { ssr: true });

export default function ConfigureAmplifyClientSide() {
  return null;
}

// app/layout.tsx: render <ConfigureAmplifyClientSide /> inside <body>

3Verify

Reload the page and call an Auth function from a component.

npm run dev

Confirmed by docs.amplify.aws

Did this fix it?

Cause 2 of 3

An Auth call runs at module level, before configuration

1Check

Calls at the top of a module run on import, which can be before the layout's configure component runs, including in child components of a Next.js layout.

grep -rn "^const .*= await fetchAuthSession\|^fetchAuthSession" --include="*.ts" --include="*.tsx" .

2Fix

Move the call into the component lifecycle, such as useEffect.

useEffect(() => {
  fetchAuthSession().then(setSession).catch(console.error);
}, []);

3Verify

Reload; the exception no longer appears in the console.

# browser DevTools > Console

Confirmed by docs.amplify.aws

Did this fix it?

Cause 3 of 3

Server code calls Amplify without the server runner

1Check

On the server there is no Amplify.configure call. A runner is created once with the config, and server code imports Auth APIs from the /server subpaths.

grep -rn "aws-amplify/auth" --include="*.ts" --include="*.tsx" .

2Fix

Create the runner in a utility file and wrap server-side Auth calls in runWithAmplifyServerContext.

// utils/amplifyServerUtils.ts
import { createServerRunner } from '@aws-amplify/adapter-nextjs';
import outputs from '../amplify_outputs.json';

export const { runWithAmplifyServerContext } = createServerRunner({
  config: outputs,
});

3Verify

Request the server-rendered page again.

npm run dev

Confirmed by docs.amplify.aws

Did this fix it?

How do I stop it coming back?

  • Configure Amplify once, in the root layout's client component.
  • Keep Amplify calls inside components or handlers, not at module level.
  • Regenerate amplify_outputs.json (npx ampx sandbox) when the backend changes.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.