Troubleshooting an OpenNext Application

Learn how to troubleshoot OpenNext apps on Azion: run locally with Azion CLI, tail logs, use Real‑Time Events, Metadata & GraphQL APIs, fix size limits and environment variables.

View as Markdown

1. Local Development and Debugging with the Azion CLI

The first and most crucial troubleshooting step is performed even before deployment. The Azion CLI allows you to run your function in a local environment that simulates the Azion platform.

Key Command:

azion dev

When you run this command in the root of your project, the CLI starts a local server. Any request made to this server will execute your function, and outputs from console.log, as well as any errors, will be displayed directly in your terminal.

Benefits:

  • Immediate Feedback: See the results of your code changes instantly.
  • Time Savings: Avoids the need to deploy for every minor change.
  • Controlled Environment: Debug your application’s logic without affecting the production environment.

Example:

// main.js
export default function myWorker(event) {
console.log("Function executed successfully!");
return new Response('Hello World');
}

After running azion dev and accessing the local server, your terminal will display:

Function executed successfully!

2. Monitoring Logs in Production

Once your application is in production, you need tools to observe its behavior in real time and analyze past events.

Real-Time Access (Tailing)

To monitor logs as they happen, use the --tail argument with the Azion CLI. This creates a continuous session that displays new logs as they are generated.

Key Command:

azion logs cells --tail

This command is ideal for debugging issues that are currently happening or for monitoring the application’s behavior during a new deployment.

Viewing via the Azion Console (Real-Time Events)

For a more visual analysis with more filtering options, the Azion Console is the ideal tool.

  1. Access the Real-Time Manager.
  2. In the menu, go to Observe > Real-Time Events.
  3. Select the Functions Console tab.

On this screen, you can:

  • View all logs generated by console.log in your functions.
  • Filter events by time periods (last 15 minutes, last hour, custom range).
  • Search for specific log messages.
  • Analyze detailed information for each event, such as Function ID and Timestamp.

3. Advanced Analysis with the Metadata API

Often, the problem lies not just in the code, but in the context of the request (origin, headers, etc.). The Azion Metadata API allows your functions to access this data. You can log this metadata to better understand your application’s behavior.

Practical Example:

Imagine you want to check which continent a request is coming from.

// main.js
export default function myWorker(event) {
const request = event.request;
const continentCode = request.metadata['geoip_continent_code'];
console.log(`Request received from continent: ${continentCode}`);
// Additional logic based on the continent...
return new Response(`Hello, ${continentCode}!`);
}

By deploying this code and monitoring the logs with azion logs cells --tail, you will see messages like:

Request received from continent: SA

This allows you to debug routing logic, security (for example, blocking by region), and content personalization.

4. Structured Log Collection with the GraphQL API

For automation, integration with external monitoring systems (like Datadog or New Relic), or for performing complex analyses, Azion provides a GraphQL API.

With it, you can execute queries to fetch logs in a structured format.

Key Tool: The GraphQL Playground, available in the Azion Console, allows you to build and test your queries before integrating them into your tools.

Example Query: This query fetches the 10 most recent Console events containing a specific log line.

query getConsoleEvents {
functionConsoleEvents(
limit: 10,
filter: {
tsRange: {begin: "2024-09-28T12:00:00", end: "2024-09-28T13:00:00"},
line: {contains: "Function failed"}
},
orderBy: [ts_ASC]
) {
ts
configurationId
functionId
line
}
}

5. Function size exceeds limit

Azion imposes limits on the size of functions, the default limit is 20MB. If your deployment fails with an error about function size, it usually means your bundled code is too large for the platform.

To resolve this:

  1. Analyze your bundle: Use tools like Webpack Bundle Analyzer or ESBuild Analyzer to identify large dependencies.
  2. Remove unused dependencies: Audit your package.json and codebase for unnecessary packages.
  3. Optimize imports: Prefer importing specific functions instead of entire libraries (for example, import { parse } from "date-fns" instead of import * as dateFns from "date-fns").
  4. Leverage Azion’s caching: Move static assets and large files to Azion’s Object Storage or CDN, and reference them via URLs instead of bundling them.

Refer to Azion’s documentation on Functions limits for up-to-date size restrictions.

6. My environment variables are not available in the Functions

Azion allows you to define environment variables for your functions, but they must be configured explicitly in the Azion Console or via the API.

If your code can’t access an expected environment variable:

  1. Check the Azion Console: Go to your Application > Functions > Environment Variables and ensure the variable is defined.
  2. Redeploy after changes: Any change to environment variables requires a redeploy of your function to take effect.
  3. Access variables correctly: In your code, use process.env.MY_VARIABLE (for Node.js compatibility) or the platform-specific API if using another runtime.

If you’re using a framework like Next.js, ensure your build process does not overwrite or ignore these variables. For more, see Azion’s guide to environment variables.