Troubleshoot configuration errors

If you are running into a missing configuration or NoCredentials error message and have called Amplify.configure in your project, your Amplify API is most likely being called before Amplify.configure. This can happen in a few different ways. Below are three possibilities you can check to troubleshoot this issue.

Check 1: Validate that `Amplify.configure` is called in the root of your project

Make sure you are calling Amplify.configure in the root file of your project. The root file of your app may be different depending on your frontend framework. The current default for some common frameworks are listed below (if you are not using TypeScript the ts and tsx extensions would be js and jsx):

Vue.js: src/main.ts
React: src/main.tsx
Angular: src/main.ts
Next.js Page Router: pages/_app.tsx or src/pages/_app.tsx
Nuxt: app.vue (Or in a plugins file, as recommended here.)

If you are using the Next.js App Router, you can follow the suggestions in our Next.js documentation for root-level configuration. Keep in mind that if you are calling any APIs at the module-level (i.e. at the top of your file) in any of the Child components, you may still run into this issue. Continue on the Check 2 if this is the case.

Check 2: Move module-level Amplify API invocations

When Amplify APIs are used outside of your application lifecycle, there is a risk that a JavaScript bundler may place that API call before Amplify.configure. Module-level function calls (calls at the top-level of a file), are generally evaluated in the order that they are imported.

Below is an example of code that will likely result in a missing configuration or NoCredentials error message:

index.ts

1import { Amplify } from 'aws-amplify';
2import ComponentX from 'module-fetch-auth';
3
4// fetchAuthSession() in ComponentX executed on import
5
6Amplify.configure();
7
8export default function App() {
9  return (
10    <div>
11        <ComponentX />
12    </div>
13  );
14}

module-fetch-auth.tsx

1import { fetchAuthSession } from 'aws-amplify/auth';
2
3fetchAuthSession(); // Will throw "AuthUserPoolException: Auth UserPool not configured."
4
5export default function ComponentX() {
6  return (
7    <div className="box">
8      ...
9    </div>
10  );
11}

This error can also happen when using Next.js Layouts and calling Amplify APIs in child components at the module-level (at the top of your file/module). See below for an example of this issue:

layout.tsx

1import ConfigureAmplifyClientSide from '@/ConfigureAmplifyClientSide';
2
3export default function RootLayout({
4  children,
5}: {
6  children: React.ReactNode;
7}) {
8  return (
9    <html lang="en">
10      <body className="container py-6">
11        <>
12          <ConfigureAmplifyClientSide />
13          {children}
14        </>
15      </body>
16    </html>
17  );
18}

ConfigureAmplifyClientSide.tsx

1import { Amplify } from "aws-amplify";
2
3Amplify.configure(config, { ssr: true });
4
5export default function ConfigureAmplifyClientSide() {
6  return null;
7}

page.tsx

1import { fetchAuthSession } from "aws-amplify/auth";
2
3// The layout calls configure, but fetchAuthSession ends up executing first
4// Will throw "AuthUserPoolException: Auth UserPool not configured."
5fetchAuthSession().then((session) => {
6  console.log(session);
7});
8
9export default function HomePage() {
10  return (
11    <div className="box">
12      ...
13    </div>
14  );
15}

To fix this, we suggest moving all Amplify API calls to within the application lifecycle. For instance, if you are using React, you can use the useEffect hook for functions that should run before the app is loaded:

index.ts

1import { Amplify } from 'aws-amplify';
2import ComponentX from 'module-fetch-auth';
3
4Amplify.configure();
5
6export default function App() {
7  return (
8    <div>
9        <ComponentX />
10    </div>
11  );
12}

module-fetch-auth.tsx

1import { type AuthSession, fetchAuthSession } from 'aws-amplify/auth';
2import { useEffect, useState } from 'react';
3
4export default function ComponentX() {
5  const [session, setSession] = useState<AuthSession|undefined>();
6
7  const getSession = async () => {
8    try {
9      const currentSession = await fetchAuthSession();
10      setSession(currentSession);
11    } catch (error: unknown) {
12      console.log(error);
13    }
14  };
15
16  useEffect(() => {
17    getSession();
18  }, []);
19
20  return (
21    <div className="box">
22      ...
23    </div>
24  );
25}

Check 3: Configure Amplify on each page of a multi-page app

If you are working in a multi-page app, you need to call Amplify.configure() for each page/route of your application. We recommend calling Amplify.configure in a common source file and importing it into each page.

Troubleshoot configuration errors

Check 1: Validate that Amplify.configure is called in the root of your project

Check 2: Move module-level Amplify API invocations

Check 3: Configure Amplify on each page of a multi-page app

Check 1: Validate that `Amplify.configure` is called in the root of your project