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.

cannot find module './chunks/xxxx.js' error

Dynamic imports in instrumentation.ts will cause this error at runtime. Remove dynamic imports to resolve.

Sentry server side setup

The config recommended by Sentry docs uses dynamic imports in instrumentation.ts, which causes the above error.

Here's a working Sentry config which resolves the error:

instrumentation.ts

import * as Sentry from "@sentry/nextjs";
import { initSentry } from "../sentry.server.config";
 
export const onRequestError = Sentry.captureRequestError;
 
export async function register() {
  initSentry(process.env.NEXT_RUNTIME as "nodejs" | "edge");
}

sentry.server.config.ts

import * as Sentry from "@sentry/nextjs";
 
export const initSentry = (runtime: "nodejs" | "edge") => {
  Sentry.init({
    dsn: "https://...",
 
    //...rest of your config
  });
};

Empty body in response when streaming in AWS Lambda

We have seen trouble in the past with streaming hanging in AWS Lambda when the response body is empty. We currently have a workaround in OpenNext for this by setting the environment variable OPEN_NEXT_FORCE_NON_EMPTY_RESPONSE to true. This will write something to the stream to make sure it is not empty.

The Yarn Plug'n'Play manifest forbids importing "xxx" here because it's not listed as a dependency of this package

This error is usually resolved by removing all yarn files in your repo. You should also look in your package.json and see if you have yarn set as packageManager there. Removing it will solve the issue. If you use yarn there is a workaround here (opens in a new tab).

If you are not using yarn and you see yarn related errors it might be solved by running corepack disable or updating nvm to 0.40.2.