Troubleshooting

Debug mode

OpenNext can be executed in debug mode by setting the environment variable OPEN_NEXT_DEBUG=true.

This will output A LOT of additional logs to the console.This also disable minifying in esbuild, and add source maps to the output. This can result in code that might be up to 2-3X larger than the production build. Do not enable this in production

OPEN_NEXT_DEBUG=true npx open-next@latest build

Cannot find module next

You might stumble upon this error inside cloudwatch logs: Cannot find module 'next'. It is likely that you are in a monorepo and you have several lock files. Just make sure that you have a single lock file in the root of your project.

Reducing bundle size

Next might incorrectly include some dependencies in the bundle. To remove them you can use this configuration inside next.config.js:

experimental: {
    outputFileTracingExcludes: {
      "*": ["node_modules/the-unwanted-package"],
    },
  },

Also you should not add sharp as a dependencies unless absolutely necessary, the image optimization already has it's own version of sharp.

Patch fetch behaviour for ISR. Only for next@13.5.1+

If you use ISR and fetch in your app, you may encounter a bug that makes your revalidate values inconsistent. The issue is that it revalidates using the lowest revalidate of all fetch calls in your page, regardless of their individual values. To fix this bug, you need to modify the fetch function in your root layout component with the following code snippet

export default function RootLayout() {
  const asyncStorage = require('next/dist/client/components/static-generation-async-storage.external');
  //@ts-ignore
  const staticStore =
    (fetch as any).__nextGetStaticStore?.() ||
    asyncStorage.staticGenerationAsyncStorage;
  const store = staticStore.getStore();
  store.isOnDemandRevalidate =
    store.isOnDemandRevalidate && !(process.env.OPEN_NEXT_ISR === 'true');
  return <>...</>;
}

Access Denied errors on routes during page refresh and direct URL access

If you are refreshing a dynamic/static route or going to that route directly from an URL. Like this route f.ex: /profile/[userId]/[id], and you are getting an Access Denied error in XML:

<Error>
   <Code>AccessDenied</Code>
   <Message>Access Denied</Message>
   <RequestId>R4E6T9G2Q1S0Z5X8</RequestId>
   <HostId>S7h9F3g2T0z5K8d6A2s1W4x3C7v8B9m2L0j3K4i7H8g9F0r3A5q8w9E8r7t6Y5h4U3i2O1p0</HostId>
</Error>

This can also happen in app router when a client navigates via NextJS <Link> component.

The issue might be that your having a folder or file in your public directory with an overlapping between the name and your route. In this case, you should rename that to something else.