Troubleshoot an OpenNext application

This page lists the symptoms an OpenNext application can show on Azion, each with its cause and its fix. The code of the application runs as a function, so the logs, limits, and environment variables of Functions apply to it. The symptoms cover errors you cannot see, request context you cannot read, a deployment refused for its size, and missing environment variables.

An error appears only after you deploy

Code that worked on your machine fails once it runs on Azion. Each attempt at a fix then takes another deployment before you can see whether it worked.

Without a local run, the deployed function is the first place your code meets Azion Runtime. Every error then costs a deployment to surface.

To catch the error before you deploy:

• Run the application locally: Azion CLI starts a local server that simulates the Azion platform. Each request you send to it executes your function. The terminal prints the console.log output of the code and any error it raises. For the command and its options, refer to Develop and test a function locally.
• Correct the code and send the request again: the change runs on your machine, with no deployment and no effect on production traffic.

The error and your log output now appear in the terminal before the code reaches production.

A deployed function fails without showing an error

In production, the application answers in a way you did not expect, and nothing tells you where the code went wrong.

A deployed function sends its console.log output and its errors to Azion, not to your terminal. Until you read them there, the only evidence you have is the response the function returned.

To read what the function logged:

• Follow new log lines from the terminal: Azion CLI streams the logs of your functions as they arrive. Use it for an issue that is happening now, or to watch the application during a new deployment.
• Filter and search the logs in Azion Console: Real-Time Events lists the console.log output of your functions. It filters the events by time period and searches them for a message. Each event shows its function ID and its timestamp.
• Query the log lines with GraphQL: the GraphQL API returns the same lines in a structured format, for automation or for a monitoring system you already run. Its functionConsoleEvents dataset returns each line with its timestamp, its function ID, and its configuration ID. A query can filter the lines by time range and by the text they contain. Build and test the query in the GraphQL Playground of Azion Console before you move it into your tools.

For the steps on each interface, refer to Troubleshoot function execution and logs.

The line your code logged, or the error the function raised, now points to the code path that failed.

Logic that depends on the request gives the wrong result

Routing, blocking by region, or content personalization does not behave as you expect for some clients.

Logic of this kind reads the context of the request, such as the place it comes from. The response does not show that context. The fault can sit in the values your code received rather than in the code itself.

To see the values your logic receives:

• Log the request metadata your logic reads: the Metadata API gives a function the context of the request, such as geoip_continent_code, the continent code of the client. Write the value with console.log next to the decision that uses it.
• Read the line in the logs: deploy the change, then read the logs from Azion CLI, Real-Time Events, or the GraphQL API. For the steps, refer to Troubleshoot function execution and logs.

Each log line now pairs the continent code of a request with the branch your code took for it.

A deployment fails because the function is too large

The deployment stops with an error about the size of the function.

The bundled code is larger than Azion accepts for one function. Functions limits caps the code at 20 MB when you deploy it through the Azion API. Code created or edited in Azion Console has a cap of 6 MB.

To bring the bundle under the limit:

• Find the large dependencies: analyze the bundle with a tool such as Webpack Bundle Analyzer or ESBuild Analyzer.
• Remove unused dependencies: check package.json and the code base for packages the application does not use.
• Import only the functions you use: import one function rather than a whole library. Write import { parse } from "date-fns" instead of import * as dateFns from "date-fns".
• Serve static assets and large files from storage: move them to Object Storage and reference them by URL instead of bundling them.
• Request a higher limit: the code size caps are defaults. To raise one for your plan, contact technical support.

With the bundle under the cap, the deployment no longer fails on the size of the function.

Environment variables are not available to the function

The code expects an environment variable and does not receive its value. Azion.env.get() returns undefined for a key that does not exist, and the function continues with that value.

A function reads only the variables that exist on the account, under the exact key the code asks for. A value you change after a deployment does not reach the function that is already running.

To make the value available:

• Create the variable on the account: manage environment variables through the Azion API, Azion CLI, or the Azion Terraform provider. Give the variable the exact key your code reads.
• Redeploy after a change: a new value does not reach a running function. Redeploy the function for the change to take effect.
• Read the variable through a supported interface: Azion.env.get() takes the key and returns the value. Azion Runtime also supports process.env for Node.js compatibility.
• Keep the build from dropping the variables: in a Next.js project, check that the build process does not overwrite or ignore them.

For the fields, the caps, and the management interfaces, refer to Environment variables.

The function now reads the value you set for the key.

Related resources