Troubleshooting

Build Failures

The most common deployment issues occur during the build phase.

Missing dependencies

Symptom: Module not found or Cannot find package errors

Solution:

• Ensure all dependencies are listed in package.json (not just devDependencies)
• Run npm install locally to verify your lockfile is up-to-date
• Push package-lock.json to your repository

Wrong Node.js version

Symptom: Syntax errors or unsupported features

Solution: Specify your Node version in package.json:

{
  "engines": {
    "node": ">=20.0.0"
  }
}

Build command fails

Symptom: Build exits with non-zero code

Solutions:

• Check the build logs for the specific error message
• Verify the build command works locally (npm run build)
• Ensure all required environment variables are set before build
• For TypeScript errors, check your tsconfig.json

Out of memory during build

Symptom: JavaScript heap out of memory or process killed

Solution: Add to your build command:

NODE_OPTIONS="--max-old-space-size=4096" npm run build

Or upgrade to a plan with more build resources.

Port mismatch

Symptom: Container starts but site shows 502/503 errors

Solution:

• Ensure your app listens on the PORT environment variable
• Default is port 3000 — make sure your start command uses this
• For Express: app.listen(process.env.PORT || 3000)

Domain Issues

Domain not resolving

Symptom: DNS_PROBE_FINISHED_NXDOMAIN or site not loading

Solutions:

• Verify your A record points to the correct IP (shown in dashboard)
• Wait for DNS propagation (up to 48 hours, usually 5-30 minutes)
• Use dig yourdomain.com or ask the AI: "Check DNS for my-site"
• Clear your local DNS cache: sudo dscacheutil -flushcache (macOS)

Wrong site showing

Symptom: Domain shows a different site or default page

Solution:

• Ensure the domain is added to the correct site in the dashboard
• Check if another site has the same domain configured
• Verify DNS points to Hostwares, not a previous hosting provider

Redirect loops

Symptom: ERR_TOO_MANY_REDIRECTS

Solutions:

• If using Cloudflare, set SSL mode to Full (Strict)
• Remove any redundant redirect rules in your app
• Ensure your app doesn't redirect HTTP to HTTPS internally (Hostwares handles this)

SSL Problems

Certificate not issuing

Symptom: SSL stuck in "pending" or site shows security warning

Solutions:

• Verify DNS A record points to the correct server IP
• If using Cloudflare, disable the orange cloud (set to DNS Only) temporarily
• Wait 10-15 minutes after DNS change for Let's Encrypt validation
• Ask the AI: "Check SSL status for my-site"

Mixed content warnings

Symptom: Page loads but browser shows "not fully secure"

Solution: Ensure all resources use https:// or protocol-relative URLs. Check for hardcoded http:// in images, scripts, or API calls.

Performance Issues

Slow response times

Possible causes:

• Cold starts — Container was sleeping. Upgrade plan for always-on
• Database queries — Optimize slow queries, add indexes
• Large bundle size — Use code splitting and lazy loading
• No caching — Add cache headers for static assets

High memory usage

Solutions:

• Check for memory leaks (event listeners, unclosed connections)
• Reduce image sizes and use CDN for assets
• Implement pagination for large data sets
• Upgrade plan for more RAM allocation

502 Bad Gateway

Common causes:

• App crashed — check runtime logs
• Port mismatch — verify PORT config
• Startup timeout — app takes too long to start
• Out of memory — container OOM killed

Container Crashes

Container keeps restarting

Diagnosis steps:

1. Check runtime logs for error messages
2. Verify all required env vars are set
3. Ensure your start command is correct
4. Check if the app crashes immediately on startup
5. Look for unhandled promise rejections or uncaught exceptions

Process killed (OOMKilled)

Symptom: Container restarts with exit code 137

Solutions:

• Profile memory usage locally
• Fix memory leaks in your application
• Upgrade to a plan with more memory
• Add NODE_OPTIONS="--max-old-space-size=256" to limit Node.js heap

Database Issues

Connection refused

Solutions:

• Verify the database container is running
• Check the connection string format
• Ensure your site and database are on the same network
• Try restarting the database container

Too many connections

Solutions:

• Use connection pooling (PgBouncer or Prisma connection pool)
• Set connection_limit in your ORM config
• Close connections properly in your application

Getting AI Help

For any issue, ask the AI assistant for diagnosis:

"My site is showing 502 errors, what's wrong?"
"Why did my last deployment fail?"
"My domain isn't working, can you check?"
"My site is slow, help me diagnose"
"My container keeps restarting, check the logs"

The AI will read your logs, check your configuration, and provide specific solutions. Complex troubleshooting costs 3-5 credits.