Fixing amplify_outputs.json Problems on Localhost

When an Amplify application fails only on localhost, I identify the backend before changing frontend code. The amplify_outputs.json file contains the endpoints and identity configuration the client uses. An old file can send a healthy interface to a deleted sandbox, another region, or a user pool where the current session has no meaning.

I debug the connection in layers: file origin, endpoint reachability, authentication, requested operation, and cache. That order prevents a 401 from turning into unrelated component changes.

Identify who generated the file

I inspect the file's data endpoint, region, and auth configuration, then compare them with the active sandbox or hosted branch. I record the command used to generate it. A file copied from a teammate or downloaded for staging should not be treated as local-sandbox configuration.

Generated configuration is not a secret store, but it still belongs to a known environment. I follow the repository's tracking policy and avoid swapping files without documenting the target.

Check the endpoint outside the page

A DNS failure, TLS failure, and GraphQL authorization response point to different layers. I confirm the hostname resolves and the API responds before looking at React state. Browser developer tools show the request URL and status; a small server-side request can remove browser caching from the test.

If the endpoint no longer exists, I regenerate outputs for the active sandbox or branch rather than editing the JSON by hand.

Match the auth mode to the schema

A public query may use an API key or guest IAM mode, while an admin mutation may require the Cognito user pool. The schema rule and client authMode must agree. I compare the failing operation with the Amplify authorization documentation and test the same call with a known identity.

A successful public list does not prove an authenticated mutation will work. I test each path on its own.

Refresh expired or foreign sessions

Local storage can retain tokens from a user pool associated with an older outputs file. I sign out, clear only the application's auth state, and sign in through the current pool. I avoid deleting all browser data before capturing the failing request because that erases useful evidence.

If the token is present, I check its issuer and expiration without publishing the token. A token from another pool should be discarded, not copied into a request header.

Regenerate instead of patching

For a deployed branch, Amplify documents npx ampx generate outputs --app-id ... --branch .... For a sandbox, I let the sandbox workflow create the matching file. Manual endpoint edits hide the source of truth and are lost on the next generation.

I restart the development server after replacing configuration and confirm the browser loaded the new endpoint. Next.js can retain environment and module state across refreshes.

Keep a short diagnostic record

I save the error category, sanitized endpoint host, expected environment, generation command, and successful verification. That record helps when the same symptom returns after a branch switch.

• Confirm file origin.
• Test endpoint reachability.
• Match auth mode and schema.
• Refresh the correct session.
• Regenerate outputs and restart localhost.

Need help with Amplify?

Terry Hunt Dev diagnoses Amplify configuration and authorization failures through AWS development support. Send the error category and environment name through the contact page, but do not send tokens or private endpoint credentials.