Debugging Issues

Intro

This guide will help you debug issues with your deployment, either at build/deploy time or run time.

Posting Screenshots/Logs/Configuration

If opening an issue, please try to post all logs you can, either from the component's deployment or logs in CloudWatch.

Also try to include what your configuration looks like, as depending on your setup, this component may route differently. For example, whether you have a base path, locales, etc. The config includes:

• next.config.js
• serverless.yml

It will also be helpful to look at what the build outputs are like. In particular if you can compare .next and .serverless_nextjs directory first and see if there are any files missing, that should have been copied from .next -> .serverless_nextjs.

Build/deploy Issues

If the component fails to deploy, you will need to debug at which step it is failing. First, run with debug flag to enable more verbose logs and also increase the stacktrace line limit, it will help you debug easily:

serverless --debug

In addition, any files used by the component is stored in two directories:

• .serverless_nextjs contains the assets that will be deployed to Lambda@Edge, S3, etc.
• .serverless contains the deployment state

Common Issues

Some of these may be covered in the README as well.

AWS Permissions

You may be missing various AWS permissions. Review the permissions section and add the appropriate ones. Some features may require additional features (for example, static regeneration requires SQS permissions.)

Files/binaries not included as expected

The component does not know about any other libraries other than Next.js, so it only includes pages/JS/JSON files from the .next directory. If you need other files to be included, you can use postBuildCommands input to execute any script in between the build and deploy steps.

Please check .serverless_nextjs to see if files are included as expected. If any files from .next are supposed to be included as part of a standard Next.js feature, feel free to open a new issue.

Runtime Issues

503 Errors

If you encounter 503 errors, please investigate CloudWatch logs at the region closest to where you accessed CloudFront to get the specific error message. Simply posting a "503 occurs" is not too helpful as it can be any issues, from your own code to this component's.

When opening an issue, please post the stack trace, and if possible share how your .serverless_nextjs, .next directories look like, as well as the content of your *manifest.json files.

Unexpected Behavior

If there is unexpected behavior (but not necessarily an error - for example a 404 or wrong routing), please try to include as much information about your project as possible, including the contents of .serverless_nextjs, .next, etc.