AuthUserPoolException: Auth UserPool not configured in a Next.js app
AuthUserPoolException: 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.
Fix it fast
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/null2Match what you see, then jump to its fix
- 1
grep finds no Amplify.configure, or only in a file the page does not import.Amplify.configure is not in the app entryFix - 2
fetchAuthSession() or similar is called at the top of an imported file, outside a component.An Auth call runs at module level, before configurationFix - 3
The error appears in a Server Component, route handler or middleware.Server code calls Amplify without the server runnerFix
- 1
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.json2Fix
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 devConfirmed by docs.amplify.aws
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 > ConsoleConfirmed by docs.amplify.aws
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 devConfirmed by docs.amplify.aws
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- RaheebA consumer app shipped to both stores from one Flutter codebase on a .NET and Azure back end.
Related fixes
Web apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
Apollo Client is blocked by CORS when the GraphQL server runs on AWS Lambda
No 'Access-Control-Allow-Origin' header is present on the requested resource.
Apollo Server does not set CORS for you when it runs behind a framework or integration, and on Lambda that layer is API Gateway.
5 causes, each with a fixWeb apps
Clerk cannot read its publishable key in a Next.js app
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is undefined
Clerk reads NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY.
3 causes, each with a fixWeb apps
The shell cannot find create-next-app
command not found: create-next-app
create-next-app is not meant to be installed as a shell command.
2 causes, each with a fixWeb apps
ESLint fails with: Cannot find module 'next/babel'
ESLint stops on the first file with a Babel or parser error instead of listing lint results
next/babel is a Babel preset that ships inside the next package.
3 causes, each with a fixWeb apps
ESLint says an element in a list is missing its key prop
react/jsx-key
react/jsx-key fires when an element returned from map, Array.from or an array literal has no key.
3 causes, each with a fix