Docs/Overview
Docs/Troubleshooting

Troubleshooting & Error Recovery

When deployments fail or return unexpected status codes, this guide provides the exact root causes, log patterns, and verified code fixes for common issues across Next.js, Node.js, and containerized runtimes.

Where to Find Your Logs

Exovon separates application telemetry into two dedicated streams to isolate packaging failures from runtime errors:

1. Build Logs

Captures dependency installation (npm ci), TypeScript compilation checks, and bundler stdout/stderr during container packaging. Accessible under Deployments → [Deployment Node].

2. Runtime Logs

Streams live container stdout/stderr, uncaught exceptions, and HTTP request access logs directly from the compute environment in Mumbai (asia-south1). Accessible under Runtime Logs.

Common Deployment & Runtime Errors

Diagnose and resolve the most frequent container build and network routing failures.

HTTP 502 Bad Gateway

Container Failed to Bind to PORT 8080

Symptom: Deployment finishes successfully, but navigating to your assigned domain returns an immediate 502 Bad Gateway or Application Offline screen.

Root Cause: The application hardcoded its HTTP listener to localhost:3000 or failed to listen on 0.0.0.0. The Edge Router dispatches inbound requests to the port specified in process.env.PORT (which defaults to 8080).

Verified Fix (Express / Node.js):

server.js
const express = require('express');
const app = express();

const port = process.env.PORT || 8080;
const host = '0.0.0.0'; // Must bind to 0.0.0.0, NOT 127.0.0.1 or localhost

app.get('/health', (req, res) => res.status(200).json({ status: 'ok' }));

app.listen(port, host, () => {
  console.log(`Server listening on http://${host}:${port}`);
});
Build Failure

Next.js Missing Standalone Output

Symptom: Build logs fail during the packaging step with error: Could not find .next/standalone/server.js.

Root Cause: Exovon compiles Next.js projects into minimal, standalone microcontainers (~85 MB) for sub-second startup latency. This requires enabling output: 'standalone' in your Next.js configuration.

Verified Fix (next.config.js / next.config.mjs):

next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone', // Enables standalone container bundling
  images: {
    formats: ['image/avif', 'image/webp'],
  },
};

module.exports = nextConfig; // or 'export default nextConfig;' in .mjs
Exit Code 137

Memory Limit Exceeded (Out Of Memory)

Symptom: The build process halts abruptly with Process terminated with signal SIGKILL (Exit code 137).

Root Cause: Compiling large applications with extensive client-side source maps, circular imports, or unoptimized bundler plugins exceeded the build runner RAM ceiling.

Recommended Mitigations:

  • Disable production browser source maps: productionBrowserSourceMaps: false in your Next.js configuration.
  • Add NODE_OPTIONS="--max-old-space-size=4096" to your project's Environment Variables.
  • Upgrade to the Pro Plan to unlock high-memory compilation runners.
Configuration

Variable Returns 'undefined' in Client Code

Symptom: An environment variable is saved in the Project Settings, but client-side code in the browser prints undefined.

Root Cause: To prevent credential leakage, Exovon isolates environment variables strictly on the server container. Modern frameworks intentionally omit variables from client bundles unless designated with framework-specific prefixes.

Prefix Guidelines:

.env.production
# For Next.js client-side code:
NEXT_PUBLIC_API_URL=https://exovon.in/api

# For Vite / React client-side code:
VITE_SUPABASE_URL=https://...
Dependency Resolution

npm ci / ERESOLVE Dependency Conflict

Symptom: Build logs display: npm ERR! code ERESOLVE or package-lock.json out of date.

Root Cause: Conflicting peer dependencies or a lockfile out of sync with package.json. Exovon executes npm ci to guarantee zero-drift reproducible builds.

Resolution:

Terminal
# Regenerate lockfile locally without modifying installed dependencies:
npm install --package-lock-only

# Commit and push to trigger a fresh build:
git add package-lock.json
git commit -m "fix: update lockfile"
git push origin main
HTTP 504 Gateway Timeout

Request Exceeded Plan Timeout Limit

Symptom: An API endpoint or Server Action hangs until the plan's request timeout ceiling is reached, returning 504 Gateway Timeout.

Root Cause: The edge router enforces bounded execution limits (10s on Free, 30s on Starter, 60s on Pro, 120s on Heavy). Common culprits include unindexed SQL queries, blocking third-party API requests, or saturated TCP connection pools.

Recommended Mitigations:

  • Use the ExoStore Serverless HTTP driver (@neondatabase/serverless) to eliminate TCP pool connection bottlenecks.
  • Add database indexes on frequently filtered columns (CREATE INDEX idx_user_id ON orders(user_id)).
  • Delegate compute-heavy batch tasks to asynchronous background queues.

Frequently Asked Questions

How do I rollback a broken deployment in an emergency?

Navigate to your project in the dashboard, open the Deployments view, find the previous stable deployment SHA, and click 'Rollback'. Traffic shifts immediately via edge routing in under 3 seconds with zero rebuild wait.

Why does my build succeed locally but fail on Exovon?

Local machines often have case-insensitive filesystems (macOS or Windows) or globally installed packages. Exovon builds run inside strict Linux container environments. Ensure file import paths match casing exactly and all required packages are declared in package.json.

Was this documentation page helpful?