Fix 'next: not found' Error in Next.js Azure Deployment

The “next: not found” error when deploying Next.js on Azure Web App occurs because the deployment process strips node_modules/.bin from the PATH environment variable. To fix this, modify your package.json start script to use the absolute path to the Next.js executable and ensure proper Node.js version configuration in Azure settings.

Contents

• Understanding the “next: not found” Error on Azure Web App
• Root Cause Analysis: Why Next.js Commands Fail on Azure
• Package.json Configuration Fix for Next.js Azure Deployment
• Azure Web App Runtime Settings and Node.js Version Compatibility
• GitHub Actions Deployment Workflow for Next.js on Azure
• Alternative Deployment Methods for Next.js Applications
• Verifying the Fix and Common Pitfalls in Next.js Azure Deployment
• Conclusion: Complete Next.js Azure Web App Deployment Checklist

Understanding the “next: not found” Error on Azure Web App

When deploying a Next.js application to Azure Web App, you might encounter the frustrating “next: not found” error message despite your application working perfectly locally. This error typically manifests as “sh: 1: next: not found” in the Azure deployment logs, indicating that the system cannot locate the Next.js executable even though your build process completes successfully.

This issue specifically affects Next.js applications deployed to Azure Web App, regardless of whether you’re using TypeScript, ESLint, or Tailwind CSS v4. The error occurs during the runtime phase when Azure attempts to start your Next.js server, not during the build process itself.

What makes this particularly confusing is that your application builds successfully and deploys without errors, suggesting all necessary files are present. Yet when Azure tries to execute the “next start” command from your package.json scripts, it fails to find the Next.js binary in the expected location.

Understanding this error requires knowing how Azure handles Node.js applications differently from your local development environment. When you run Next.js locally, your shell has access to the node_modules/.bin directory through the PATH environment variable, allowing direct execution of commands like “next”. However, Azure’s deployment process modifies this environment, creating the “next: not found” condition.

Root Cause Analysis: Why Next.js Commands Fail on Azure

The fundamental reason for the “next: not found” error lies in how Azure Web App handles the PATH environment variable during the deployment and startup process. When you deploy a Next.js application to Azure using ZIP deployment or GitHub Actions, the platform performs several configuration steps that affect where executable binaries can be found.

In your local development environment, when you run npm start or next start, your shell looks for executables in several directories, including node_modules/.bin. This directory contains symlinks to the actual Next.js executable, allowing you to run commands like next directly. Azure’s deployment process, however, strips this directory from the PATH environment variable for security and isolation reasons.

This behavior is particularly problematic for Next.js because the framework relies on its own executable rather than being invoked directly through Node.js. While locally you might have scripts like "start": "next start" in your package.json, this fails on Azure because the shell can’t find the next command.

Another contributing factor is Azure’s handling of Node.js versions. When you specify Node.js 24 LTS in your Azure configuration, the platform sets up the environment with that specific version, but this process doesn’t automatically restore the full PATH that includes all your project’s local binaries.

The combination of these factors—PATH modification and Node.js version management—creates a scenario where your Next.js application builds successfully but cannot start properly on Azure. This is why you see the error message “sh: 1: next: not found” rather than a more typical Node.js error, indicating the shell itself cannot locate the executable.

Package.json Configuration Fix for Next.js Azure Deployment

The most reliable solution to the “next: not found” error is to modify your package.json scripts to use absolute paths to the Next.js executable rather than relying on the PATH environment variable. This approach works consistently across different deployment environments, including Azure Web App.

First, locate your package.json file and find the “scripts” section. You’ll need to update the “start” script to use the full path to the Next.js binary:

{
 "scripts": {
 "dev": "next dev",
 "build": "next build",
 "start": "node_modules/next/dist/bin/next start",
 "lint": "next lint"
 }
}

This change explicitly tells Node.js to execute the Next.js binary from its location within the node_modules directory, bypassing any PATH environment variable issues. The absolute path node_modules/next/dist/bin/next points directly to the Next.js executable, ensuring it can be found regardless of how Azure configures the environment.

For TypeScript applications, this solution maintains compatibility with your existing TypeScript configuration. The Next.js compiler continues to handle TypeScript files during the build process, and the updated start script simply uses a different method to invoke the Next.js server.

If you’re using Tailwind CSS v4, this fix doesn’t affect your CSS processing workflow. Tailwind will still correctly compile your styles during the build phase, and the server startup will proceed normally with the updated script.

Another benefit of this approach is that it doesn’t require any changes to your deployment process or Azure configuration. You can continue using your existing GitHub Actions workflow or ZIP deployment method—only the package.json needs modification.

After making this change, commit and redeploy your application to Azure. The “next: not found” error should be resolved, and your Next.js application should start successfully on the Azure Web App.

Azure Web App Runtime Settings and Node.js Version Compatibility

Even with the package.json fix, proper Node.js version configuration in Azure Web App is crucial for Next.js deployment compatibility. While Node.js 24 LTS is the latest version, it currently has compatibility issues with Next.js on Azure App Service. Instead, you should use Node.js 20 LTS for optimal results.

For Windows-based Azure Web Apps, configure the Node.js version through the Application Settings:

1. Navigate to your Azure Web App in the Azure Portal
2. Go to “Configuration” > “Application settings”
3. Add or update the setting WEBSITE_NODE_DEFAULT_VERSION with the value ~20
4. Save the changes and restart your Web App

For Linux-based Azure Web Apps, the configuration is slightly different. Linux environments use the linuxFxVersion setting to specify the Node.js runtime:

1. In your Azure Web App configuration, find the “Platform features” section
2. Select “Configuration” > “General settings”
3. Set the “Stack” to “Node” and the “Node version” to “20 LTS”
4. Alternatively, set the linuxFxVersion setting to NODE|20.14.0

These settings ensure Azure provisions the correct Node.js environment for your Next.js application. The Node.js 20 LTS version provides better compatibility with Next.js than the newer 24 LTS, which has some known issues on Azure’s platform.

If you absolutely must use Node.js 24 LTS for your Next.js application, you may need to implement additional workarounds, such as:

1. Creating a custom startup script that manually adds the node_modules/.bin directory to the PATH
2. Using a different deployment method like Azure Container Apps
3. Implementing a self-contained deployment package with nextjs-standalone-deployer

However, these approaches add complexity and are generally unnecessary when Node.js 20 LTS works perfectly well with Next.js on Azure.

Remember to test your application thoroughly after making these configuration changes, especially if your project uses TypeScript, ESLint, or Tailwind CSS v4, as these frameworks may have specific requirements that interact with the Node.js runtime environment.

GitHub Actions Deployment Workflow for Next.js on Azure

If you’re using GitHub Actions to deploy your Next.js application to Azure Web App, you’ll need to modify your workflow to ensure build artifacts are preserved during deployment. Azure’s default deployment process sometimes excludes the .next directory, which contains the compiled application.

Here’s an improved GitHub Actions workflow that properly handles Next.js deployment to Azure:

name: Deploy Next.js to Azure

on:
 push:
 branches:
 - main
 workflow_dispatch:

jobs:
 build-and-deploy:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 
 - name: Set up Node.js
 uses: actions/setup-node@v4
 with:
 node-version: '20'
 cache: 'npm'
 
 - name: Install dependencies
 run: npm ci
 
 - name: Build Next.js application
 run: npm run build
 
 - name: Zip artifact for deployment
 run: zip next.zip ./* .next -qr
 
 - name: Deploy to Azure Web App
 uses: azure/webapps-deploy@v2
 with:
 app-name: ${{ secrets.AZURE_WEBAPP_NAME }}
 publish-profile: ${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}
 package: next.zip

Key improvements in this workflow:

1. Node.js 20: Explicitly sets up Node.js 20, which is compatible with Next.js on Azure
2. Build step: Runs npm run build to compile your Next.js application
3. Artifact zipping: Creates a ZIP file that includes both the source files and the .next directory
4. Preserved artifacts: The -qr flag ensures quiet operation and recursive inclusion of files

This workflow addresses the issue where Azure might otherwise exclude the .next directory during deployment. By explicitly including it in the ZIP file, you ensure the compiled application is available when Azure starts your Web App.

If your project uses TypeScript, the build step will compile your TypeScript files into JavaScript before deployment. For Tailwind CSS v4, the build process will generate your styles and ensure they’re included in the final artifact.

The workflow also caches npm dependencies to speed up subsequent deployments, a feature particularly useful for larger Next.js applications with many dependencies.

After implementing this workflow, your GitHub Actions deployment should successfully deploy your Next.js application to Azure without the “next: not found” error, provided you’ve also updated your package.json start script as described in the previous section.

Alternative Deployment Methods for Next.js Applications

While the package.json and GitHub Actions fixes are the most common solutions for the “next: not found” error, there are alternative deployment methods you can consider if you encounter persistent issues or want to explore different approaches.

Standalone Deployment Package

One robust alternative is to create a standalone deployment package using nextjs-standalone-deployer. This tool packages your Next.js application in a way that doesn’t depend on the node_modules/.bin directory being in the PATH.

First, install the tool as a development dependency:

npm install nextjs-standalone-deployer --save-dev

Then modify your build script in package.json:

{
 "scripts": {
 "build": "next build && nextjs-standalone-deployer",
 "start": "node server.js"
 }
}

The standalone deployer creates a build folder containing all necessary files to run your Next.js application independently. You then deploy only this build folder to Azure, rather than your entire project structure.

This approach works particularly well for TypeScript applications because it includes the compiled JavaScript in the standalone package. Tailwind CSS v4 styles are also properly processed and included in the final package.

Azure Container Apps

For more complex Next.js applications or those requiring specific Node.js versions that aren’t fully supported on Azure Web App, consider deploying to Azure Container Apps. Containerized deployment provides more control over the runtime environment:

1. Create a Dockerfile for your Next.js application
2. Build and push the container image to Azure Container Registry
3. Deploy the container to Azure Container Apps

Your Dockerfile might look like this:

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .

RUN npm run build

EXPOSE 3000

CMD ["npm", "start"]

This method gives you complete control over the Node.js version and environment configuration, solving compatibility issues that might arise with Next.js on Azure Web App.

Manual ZIP Deployment with Custom Startup Script

If you prefer not to modify your package.json, you can create a custom startup script that manually adds the node_modules/.bin directory to the PATH before starting Next.js.

1. Create a file named start.sh in your project root:

#!/bin/bash

# Add node_modules/.bin to PATH
export PATH=$PATH:$(pwd)/node_modules/.bin

# Start Next.js
npm start

2. Make the script executable: chmod +x start.sh
3. Update your Azure Web App configuration to use this script as the startup command

This approach maintains your existing package.json scripts while working around Azure’s PATH limitations.

Each of these alternative methods has its own advantages and trade-offs in terms of complexity, deployment speed, and maintainability. The package.json fix remains the simplest solution for most Next.js applications, but these alternatives provide flexibility when dealing with specific constraints or requirements.

Verifying the Fix and Common Pitfalls in Next.js Azure Deployment

After implementing the fixes described in this guide, you’ll want to verify that your Next.js application is working correctly on Azure Web App. Here’s a systematic approach to testing and troubleshooting:

Verification Steps

1. Check the deployment logs: In the Azure Portal, navigate to your Web App and select “Deployment center” or “Logs” to view the deployment process. Look for successful deployment followed by successful application startup.

2. Test the application: Access your deployed application using the provided URL. Verify that all pages load correctly, especially those that use TypeScript features or Tailwind CSS v4 styling.

3. Check specific functionality: Test any API routes, authentication, or database connections specific to your application.

4. Monitor performance: Use Azure Application Insights to monitor your application’s performance and identify any issues that might arise from the deployment configuration changes.

Common Pitfalls to Avoid

1. Incomplete package.json modification: Ensure you’ve updated both the “start” script in package.json and any other scripts that invoke Next.js commands. Missing even one script can lead to deployment issues.

2. Node.js version mismatch: Double-check that your Azure Web App is configured to use Node.js 20 LTS, not 24 LTS. This is a common oversight that can cause deployment failures even with the package.json fix.

3. Missing build artifacts: If using GitHub Actions, ensure your workflow includes the .next directory in the deployment package. Without this, your application won’t have the compiled code needed to run.

4. Environment variables: Remember to configure any environment variables your Next.js application relies on, such as database connection strings or API keys. Azure Web App Application Settings is where these should be configured.

5. Custom domain and SSL: If using a custom domain, ensure your SSL certificate is properly configured in Azure. SSL issues can sometimes manifest as application startup problems.

Troubleshooting Persistent Issues

If you continue to experience the “next: not found” error or other deployment issues after implementing these fixes:

1. Enable verbose logging: In your Azure Web App configuration, enable detailed logging and set the logging level to “Verbose” to get more information about the startup process.

2. Check file permissions: Ensure that all necessary files and directories have the correct permissions, particularly the node_modules directory and the Next.js executable.

3. Test with a minimal Next.js application: Create a minimal Next.js application without TypeScript, ESLint, or Tailwind CSS to isolate whether the issue is with your specific configuration or with the Azure deployment process itself.

4. Review Azure Web App configuration: Double-check all settings in your Azure Web App, including the stack type (Windows vs. Linux), Node.js version, and application settings.

5. Consult Azure documentation: Check the latest Azure documentation for any updates or changes to how Next.js applications are deployed, as platform configurations can evolve over time.

By following these verification steps and being aware of common pitfalls, you can ensure your Next.js application deploys successfully to Azure Web App and continues to function properly in the production environment.

Conclusion: Complete Next.js Azure Web App Deployment Checklist

Successfully deploying a Next.js application to Azure Web App requires attention to several configuration details beyond simply uploading your code. By following this comprehensive checklist, you can avoid the “next: not found” error and ensure your TypeScript, ESLint, and Tailwind CSS v4 application runs smoothly on Azure.

Pre-Deployment Checklist

• [ ] Verify Node.js version: Use Node.js 20 LTS instead of 24 LTS for Azure compatibility
• [ ] Update package.json scripts: Modify the “start” script to use absolute path: “start”: “node_modules/next/dist/bin/next start”
• [ ] Test locally: Verify your application works with the updated scripts before deployment
• [ ] Configure TypeScript: Ensure TypeScript files compile correctly with your updated configuration
• [ ] Verify Tailwind CSS v4: Confirm your styles are properly generated during build
• [ ] Check dependencies: Review package.json for any dependencies that might have compatibility issues

Azure Web App Configuration

• [ ] Set Node.js version: Configure Azure Web App to use Node.js 20 LTS (Windows: set WEBSITE_NODE_DEFAULT_VERSION to “~20”; Linux: set linuxFxVersion to “NODE|20.14.0”)
• [ ] Configure application settings: Add any required environment variables in Azure Web App configuration
• [ ] Enable logging: Set up detailed logging to troubleshoot any deployment issues
• [ ] Check platform settings: Verify your Web App is configured for the appropriate platform (Windows or Linux)

Deployment Process

• [ ] Update GitHub Actions workflow: Ensure your workflow includes the .next directory in the deployment package
• [ ] Test deployment: Perform a test deployment to catch any issues before going live
• [ ] Verify build artifacts: Confirm the .next directory is included in your deployment package
• [ ] Review deployment logs: Check for any warnings or errors during the deployment process

Post-Deployment Verification

• [ ] Access application: Visit your deployed URL to verify the application loads correctly
• [ ] Test all pages: Navigate through your application to ensure all functionality works
• [ ] Check TypeScript features: Verify any TypeScript-specific features are functioning
• [ ] Confirm Tailwind CSS styles: Ensure your styling is applied correctly
• [ ] Monitor performance: Use Azure monitoring tools to watch for performance issues
• [ ] Set up monitoring: Configure Application Insights or similar for ongoing monitoring

Maintenance and Updates

• [ ] Regular updates: Keep your Next.js and Node.js versions up to date while maintaining Azure compatibility
• [ ] Dependency management: Regularly review and update your application dependencies
• [ ] Performance monitoring: Continuously monitor your application’s performance on Azure
• [ ] Error tracking: Implement error tracking to catch issues proactively

By systematically following this checklist, you can successfully deploy Next.js applications to Azure Web App without encountering the “next: not found” error. The combination of proper package.json configuration, Azure Web App settings, and a robust deployment workflow will ensure your TypeScript, ESLint, and Tailwind CSS v4 applications run smoothly in the Azure environment.

Remember that Azure’s platform configuration can evolve over time, so always check the latest Azure documentation for any updates to Next.js deployment recommendations. With the right configuration, Azure Web App provides an excellent hosting environment for Next.js applications, offering scalability, reliability, and integration with the broader Azure ecosystem.

Sources

1. Stack Overflow: Next.js Azure Deployment Fix — Solution for resolving “next: not found” error on Microsoft Azure Web App: https://stackoverflow.com/questions/79636999/how-to-resolve-next-not-found-error-on-microsoft-azure-web-app

2. Microsoft Q&A: Node.js Version Compatibility — Official guidance on Node.js version requirements for Next.js on Azure App Service: https://learn.microsoft.com/en-us/answers/questions/5587129/deploying-next-js-app-to-azure-and-not-working

3. Stack Overflow: Alternative Deployment Methods — Additional approaches for deploying Next.js standalone in Azure Web App: https://stackoverflow.com/questions/77430438/error-next-not-found-while-starting-nextjs-standalone-in-azure-web-app

4. Azure Web App Documentation — Official documentation for configuring Node.js applications on Azure Web App: https://learn.microsoft.com/en-us/azure/app-service/quickstart-nodejs?pivots=platform-linux

5. Next.js Documentation — Official Next.js deployment documentation for Azure and other platforms: https://nextjs.org/docs/deployment

6. GitHub Actions Azure Deployment — GitHub Actions workflow examples for deploying to Azure Web App: https://learn.microsoft.com/en-us/azure/developer/github/actions/deploy-to-azure-web-app-using-github-actions

7. Azure App Service Node.js Guide — Comprehensive guide for Node.js applications on Azure App Service: https://learn.microsoft.com/en-us/azure/app-service/containers/tutorial-nodejs-mongodb-app

8. Next.js Node.js Compatibility — Official Next.js documentation on Node.js version requirements: https://nextjs.org/docs/basic-features/nodejs-versions

9. Azure Web App Configuration — Azure documentation on Web App configuration settings: https://learn.microsoft.com/en-us/azure/app-service/configure-common

10. Node.js Runtime on Azure — Microsoft guidance on Node.js runtime options and configurations: https://learn.microsoft.com/en-us/azure/app-service/containers/tutorial-nodejs-mongodb-app#configure-the-nodejs-runtime

Conclusion

Deploying Next.js applications to Azure Web App can be challenging when encountering the “next: not found” error, but with the right configuration changes, this issue is easily resolved. By updating your package.json scripts to use absolute paths to the Next.js executable and ensuring proper Node.js version compatibility, you can successfully deploy your TypeScript, ESLint, and Tailwind CSS v4 applications to Azure.

The key takeaways from this guide are:

1. Modify your package.json start script to use “node_modules/next/dist/bin/next start” instead of “next start”
2. Use Node.js 20 LTS instead of 24 LTS for Azure compatibility
3. Configure your GitHub Actions workflow to include the .next directory in the deployment package
4. Test thoroughly after making configuration changes

With these adjustments, your Next.js application should deploy and run successfully on Azure Web App, providing a reliable and scalable hosting solution for your web applications.