Common Issues & Troubleshooting

Quick solutions to the most common problems you may encounter while using Aureon.

When building, deploying, or operating applications on Aureon, issues generally fall into one of three distinct phases: Build problems (the source code failed to compile or package), Deployment problems (the build succeeded, but the platform could not launch the workload or complete health checks), or Runtime problems (the application is running, but encounters unhandled server exceptions or return errors). Use this guide to systematically isolate root causes and resolve issues quickly.

1. Deployment Failed

If a deployment fails, follow this systematic 8-step triage process:

  1. Open the affected project in your Aureon dashboard.
  2. Select the failed deployment from the project deployment history table.
  3. Review the build and deployment logs in the console log stream.
  4. Locate the first actual error rather than the final exit failure message. Downstream errors often cascade from an initial missing package or invalid path.
  5. Check your build command and framework configuration (e.g. npm run build, output directory, Node.js version).
  6. Check required environment variables to ensure all necessary build-time credentials and configuration keys are present.
  7. Confirm that the correct branch and repository are connected and containing the latest commits.
  8. Trigger a redeployment after committing your code fix or saving your project configuration.

Common Causes

  • Dependency installation failure: Network timeout, missing lockfile sync, or package registry 404s.
  • Build command failure: Syntax errors, missing build scripts in package.json, or strict linter/TypeScript aborts.
  • Missing environment variables: Build tools expecting environment keys (e.g. API endpoints, public tokens) during compilation.
  • Incorrect project configuration: Invalid root directory or mismatched build output directory (e.g. dist vs build vs .next).
  • Unsupported runtime requirement: Custom native binaries or unsupported Node engine ranges.
  • Application code error: Unhandled compile-time exceptions or broken imports.
Note: Never claim a specific cause until verified in the logs. Always inspect raw deployment logs to confirm the exact failure reason.

2. Build Failed

When the build phase fails, Aureon was unable to compile, bundle, or generate static assets for your application. Check the build logs first.

What to Look for in Build Logs

  • Package installation errors: Missing peer dependencies, incompatibilities between npm and yarn lockfiles, or packages failing to build from source.
  • TypeScript errors: Strict type validation failures in tsc during build execution.
  • Missing modules: Modules referenced in source code that are missing from package.json or mistakenly installed under devDependencies when needed in production.
  • Missing environment variables: Client-side frameworks that validate environment variables during the build phase (such as NEXT_PUBLIC_* or VITE_*).
  • Framework configuration errors: Syntax mistakes or invalid options in files like next.config.js, vite.config.js, or remix.config.js.
  • Invalid build commands: A custom build command specified in project settings that does not match any script in your repository.

How to Fix Build Errors

If the error originates from application source code, reproduce and test the build command locally in a clean directory:

npm run build

Once resolved, commit and push your changes to trigger a new deployment. If the build command or output directory setting in Aureon was configured incorrectly, update the project settings in the console and click Redeploy.

3. Application Is Not Starting

If the build phase completes successfully and the deployment status shows ready, but the web application fails to respond or returns 502/503 errors, check the following six areas:

  1. Runtime logs: Inspect the live container stdout/stderr stream for unhandled startup crashes, unhandled promise rejections, or missing modules.
  2. Application start command: Confirm that your package.json contains a valid start script (e.g. "start": "node server.js" or "start": "next start") that boots the web server.
  3. Required environment variables: Verify that server-side database connection strings, secret keys, and runtime configurations are defined for the target environment.
  4. Port configuration: Ensure your server listens on the standard environment port (process.env.PORT) and binds to all interfaces (0.0.0.0) rather than strictly localhost or 127.0.0.1.
  5. Runtime compatibility: Verify that your project's Node.js version requirements match the container runtime.
  6. Recent code changes: Inspect recent commits for long-running blocking operations or database connection attempts that halt server initialization.

4. Custom Domain Is Not Working

If your custom domain does not resolve or displays an error page, walk through this verification checklist:

  1. Project assignment: Ensure the domain is added to the correct Aureon project.
  2. DNS records match: Verify that your DNS provider (Cloudflare, GoDaddy, Namecheap, Route 53, etc.) has the exact CNAME or A records specified in the Aureon domain settings.
  3. DNS propagation: DNS updates take time to propagate across global DNS resolvers. Allow sufficient time for TTL expiration before making further adjustments.
  4. Domain verification: Confirm that Aureon has completed domain ownership verification.
  5. Conflicting DNS records: Ensure there are no conflicting A or CNAME records from previous hosting providers pointing to the same host name.
  6. SSL/HTTPS provisioning: Confirm that SSL certificate provisioning has finished for the domain.
Note on DNS Propagation: DNS changes depend on your registrar's Time-To-Live (TTL) settings and worldwide recursive resolver caches. While propagation often occurs within 15 to 30 minutes, it can take up to several hours under certain configurations.

5. HTTPS / SSL Issues

Aureon automatically provisions and manages SSL/TLS certificates for verified custom domains. If you experience HTTPS connection warnings:

  • Domain verification: Confirm that your domain has passed Aureon verification checks. Certificates cannot be issued until ownership is verified.
  • DNS configuration: Ensure the domain points cleanly to Aureon. Certificate Authorities validate HTTP-01 or DNS-01 challenges against the configured records.
  • Certificate status: Inspect the SSL status indicator in project domain settings. If certificate generation is in progress, allow a few moments for completion.
  • CAA DNS records: If your domain registrar has CAA (Certification Authority Authorization) records configured, ensure they permit standard certificate authorities (such as Let's Encrypt) to issue certificates for your domain.
Automated Certificates: You do not need to manually generate, upload, or renew SSL certificates. Aureon manages edge SSL certificates automatically.

6. Environment Variable Missing

If your application reports that an expected environment variable is undefined or missing at runtime:

  1. Check variable name spelling: Environment variable names are strictly case-sensitive. DATABASE_URL is not equivalent to database_url or Database_Url.
  2. Check variable value: Ensure the value contains no unwanted surrounding whitespace or mismatched quotation marks.
  3. Confirm environment scope: Aureon supports scoping variables to specific environments (Production, Preview, or Development). Confirm the variable is assigned to the environment currently being run.
  4. Trigger a redeployment: Updating environment variables does not retroactively modify running deployments. You must trigger a new deployment for new variables to be injected into the build and container environment.
Security Best Practice: Never commit API keys, database credentials, or authentication tokens into source control. Always configure them as Aureon Environment Variables.

7. Repository Connection Failed

If Aureon cannot access, clone, or listen to webhooks from your Git repository:

  • Git provider authorization: Verify that your Aureon account maintains active authorization with your Git provider (e.g. GitHub).
  • Repository permissions: Ensure your user account possesses read/admin permissions for the repository, and that organization-level access policies permit third-party applications.
  • Repository visibility: Confirm the repository has not been renamed, archived, transferred, or deleted.
  • Access tokens & reconnection: If credentials expired or permissions changed on GitHub, navigate to Account Settings in Aureon and reconnect your Git provider.

8. Deployment Is Stuck

If a deployment remains in a "Queued" or "Building" state for an unusually long duration:

  1. Wait briefly and refresh: Network hiccups can delay browser status updates. Refresh the deployment dashboard.
  2. Check log streaming: Determine whether build logs are actively updating or have ceased printing output.
  3. Check for interactive commands: Ensure build scripts do not run interactive commands waiting for user confirmation (e.g., npm init or interactive prompts). Build commands must run non-interactively.
  4. Check terminal status: Check whether the build timed out or entered a terminal failure state.
  5. Retry the deployment: If the deployment is stalled, cancel the in-flight build and start a new deployment.

If a deployment remains stuck on the platform level, reach out to Aureon support with your Project Name and Deployment ID.

9. Application Returns an Error

When an application fails, diagnosing the problem begins with distinguishing between three core failure modes:

Build Problem vs. Deployment Problem vs. Runtime Problem

  • Build Problem: The application failed to compile or package. The deployment never reached ready state, no containers were launched, and traffic was never routed to this version. Solution: Check build logs, test build commands locally.
  • Deployment Problem: The build completed successfully, but the platform was unable to verify health checks, allocate runtime containers, or bind ports. Solution: Check start commands, port configuration, and container memory requirements.
  • Runtime Problem: The application is active and running, but incoming web requests return HTTP 500, 502, or 504 status codes. Solution: Check live runtime logs, unhandled application exceptions, database availability, and external API integrations.

Runtime Triage Checklist

  1. Review container runtime logs for stack traces and uncaught exceptions.
  2. Verify database connectivity and confirm firewall rules allow connections from cloud containers.
  3. Check third-party API rate limits and secret validity.
  4. Inspect recent code commits for breaking changes or schema mismatches.

10. Usage Limit Reached

Aureon plans feature clear, transparent usage limits designed for predictability:

  • Unlimited Projects: All plans (Free, Pro, Business) allow unlimited projects.
  • Unlimited Bandwidth: Data transfer bandwidth is unlimited across all plans.
  • Deployments: Monthly deployment allowances (Free: 100/mo, Pro: 1,000/mo, Business: 5,000/mo).
  • Build Minutes: Amount of build and compilation compute time consumed by deployments (Free: 300, Pro: 2,000, Business: 6,000).
  • Storage: Static asset and artifact storage (Free: 5 GB, Pro: 50 GB, Business: 250 GB).
  • Edge Requests: Global CDN edge requests (Free: 250K, Pro: 10M, Business: 50M).
  • Custom Domains: Linked custom domains (Free: 3, Pro: 25, Business: 100).
  • Containers: Isolated runtime container instances (Free: 1, Pro: 5, Business: 20).
  • Runtime Hours: Active container runtime execution hours (Free: 20 hrs, Pro: 250 hrs, Business: 1,000 hrs).

When your usage approaches a plan limit, Aureon alerts you within the console. Aureon does not bill surprise overages. If your workload requires higher capacity, you can upgrade seamlessly from your billing dashboard.

11. When to Contact Support

You should contact Aureon support when you encounter issues that cannot be resolved through application adjustments:

  • A platform-level error persists after verifying code and project settings.
  • A deployment repeatedly fails without generating clear application error logs.
  • A custom domain remains unverified despite correct, globally propagated DNS records.
  • Billing or plan details appear incorrect.
  • Platform infrastructure or console services appear unavailable.

What to Provide When Contacting Support

  1. Your account email address
  2. Project name and Project ID
  3. Deployment ID of the affected deployment
  4. Exact error message or HTTP status code received
  5. Relevant snippets from build or runtime logs
  6. Approximate timestamp when the issue occurred
  7. Steps to reproduce the problem
Important Security Reminder: Never send passwords, API secrets, private keys, or authentication tokens in support messages. Aureon support staff will never request your private secrets.

Explore

Pages
Buy