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.
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):
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}`);
});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):
/** @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 .mjsMemory 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: falsein 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.
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:
# For Next.js client-side code:
NEXT_PUBLIC_API_URL=https://exovon.in/api
# For Vite / React client-side code:
VITE_SUPABASE_URL=https://...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:
# 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 mainRequest 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.