Troubleshooting Guide

This guide helps you diagnose and resolve common issues with Deployxa.

Build Failures

Module Not Found

Error:

Module not found: Can't resolve 'package-name'

Cause: Missing dependency in package.json or incorrect import path.

Solution:

1. Check package.json:

   npm install package-name
   git add package.json package-lock.json
   git commit -m "Add missing dependency"
   git push

2. Verify import path:

   // ❌ Wrong
   import utils from './util';
   
   // ✅ Correct
   import utils from './utils';

3. Clear build cache:

   deployxa deploy --no-cache

Build Command Failed

Error:

Command failed: npm run build

Cause: Build script error or missing configuration.

Solution:

1. Test locally:

   npm run build

2. Check build logs:

   deployxa logs <deployment-id> --type build

3. Verify build command:

   • Go to Project → Settings → Build
   • Ensure build command is correct
   • Common commands:
     • Next.js: npm run build
     • React: npm run build
     • Vue: npm run build
     • Laravel: composer install --no-dev

TypeScript Compilation Error

Error:

error TS2307: Cannot find module 'module-name'

Cause: Missing TypeScript definitions or incorrect tsconfig.json.

Solution:

1. Install type definitions:

   npm install --save-dev @types/module-name

2. Check tsconfig.json:

   {
     "compilerOptions": {
       "moduleResolution": "node",
       "esModuleInterop": true
     }
   }

3. Exclude node_modules:

   {
     "exclude": ["node_modules"]
   }

Out of Memory During Build

Error:

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed

Cause: Build process requires more memory than allocated.

Solution:

1. Increase Node memory:

   {
     "scripts": {
       "build": "node --max-old-space-size=4096 node_modules/.bin/next build"
     }
   }

2. Optimize build:

   • Reduce bundle size
   • Use code splitting
   • Enable tree shaking

3. Upgrade plan:

   • Pro tier has more memory
   • Enterprise tier has custom limits

Runtime Errors

Application Crashes on Start

Error:

Error: listen EADDRINUSE: address already in use :::3000

Cause: Port conflict or incorrect port configuration.

Solution:

1. Use environment variable:

   const port = process.env.PORT || 3000;
   app.listen(port);

2. Check start command:

   • Ensure start command uses correct port
   • Deployxa automatically sets PORT environment variable

Database Connection Failed

Error:

Error: connect ECONNREFUSED 127.0.0.1:5432

Cause: Incorrect database credentials or database not accessible.

Solution:

1. Verify credentials:

   DATABASE_URL=postgresql://user:pass@host:5432/db

2. Check database host:

   • Use external database host, not localhost
   • Ensure database is publicly accessible or use VPN

3. Test connection:

   psql $DATABASE_URL

Environment Variable Missing

Error:

Error: Environment variable not found: API_KEY

Cause: Required environment variable not set.

Solution:

1. Add variable:

   deployxa env add API_KEY your-api-key --project my-app

2. Verify in dashboard:

   • Go to Project → Environment
   • Check variable exists
   • Ensure correct environment (production, preview, development)

3. Redeploy:

   deployxa deploy --project my-app

CORS Error

Error:

Access to fetch at 'https://api.example.com' from origin 'https://my-app.deployxa.app' has been blocked by CORS policy

Cause: API server not configured to allow requests from your domain.

Solution:

1. Configure CORS on API server:

   // Express.js
   const cors = require('cors');
   app.use(cors({
     origin: 'https://my-app.deployxa.app'
   }));

2. Use proxy:

   // next.config.js
   module.exports = {
     async rewrites() {
       return [
         {
           source: '/api/:path*',
           destination: 'https://api.example.com/:path*'
         }
       ];
     }
   };

Domain Issues

DNS Not Propagating

Problem: Domain verification failing or SSL not provisioning.

Cause: DNS records not configured correctly or not propagated.

Solution:

1. Verify DNS records:

   dig example.com A
   dig www.example.com CNAME

2. Check required records:

   • Apex domain: A record pointing to 76.76.21.21
   • Subdomain: CNAME pointing to cname.deployxa.com

3. Wait for propagation:

   • DNS can take up to 48 hours
   • Use online tools to check propagation
   • Most changes propagate within 15 minutes

4. Re-verify:

   deployxa domain verify example.com --project my-app

SSL Certificate Pending

Problem: SSL certificate shows "Pending" for too long.

Cause: DNS not verified or Let's Encrypt rate limit.

Solution:

1. Verify domain first:

   • Ensure domain is verified
   • Check DNS records are correct

2. Check rate limits:

   • Let's Encrypt has rate limits
   • Wait 1 hour and retry

3. Manual verification:

   deployxa domain ssl example.com --project my-app

Deployment Issues

Deployment Stuck in Queue

Problem: Deployment shows "Queued" for too long.

Cause: Build workers busy or system issue.

Solution:

1. Check system status:

   • Visit status.deployxa.com
   • Check for ongoing incidents

2. Cancel and retry:

   deployxa deployment cancel <deployment-id>
   deployxa deploy --project my-app

3. Contact support:

   • If issue persists > 30 minutes
   • Email: support@deployxa.com

Deployment Timeout

Problem: Deployment takes too long and times out.

Cause: Large dependencies, slow build, or network issues.

Solution:

1. Optimize build:

   • Use npm ci instead of npm install
   • Enable dependency caching
   • Reduce build steps

2. Check build logs:

   deployxa logs <deployment-id> --type build

3. Upgrade plan:

   • Pro tier has faster build workers
   • Enterprise tier has dedicated resources

Rollback Failed

Problem: Rollback to previous deployment fails.

Cause: Previous deployment no longer available or configuration changed.

Solution:

1. Check deployment history:

   deployxa deployment list --project my-app

2. Verify deployment exists:

   • Only successful deployments can be rolled back to
   • Check deployment is not deleted

3. Manual rollback:

   • Create new deployment from previous commit
   • Or redeploy specific branch

Performance Issues

Slow Application

Problem: Application responds slowly.

Cause: Insufficient resources, unoptimized code, or database issues.

Solution:

1. Check metrics:

   deployxa metrics --project my-app --period 24h

2. Increase resources:

   • Upgrade plan for more CPU/RAM
   • Enable auto-scaling

3. Optimize application:

   • Enable caching
   • Use CDN for static assets
   • Optimize database queries
   • Minimize bundle size

4. Monitor logs:

   deployxa logs --project my-app --type runtime --follow

High Error Rate

Problem: Many requests returning 5xx errors.

Cause: Application bugs, resource limits, or external service failures.

Solution:

1. Check error logs:

   deployxa logs --project my-app --type error

2. Monitor metrics:

   deployxa metrics --project my-app --metric errors

3. Check external services:

   • Verify database connection
   • Check third-party API status
   • Review environment variables

4. Enable alerts:

   • Set up error rate alerts
   • Configure notifications

Billing Issues

Payment Failed

Problem: Payment method declined or failed.

Cause: Insufficient funds, expired card, or bank issue.

Solution:

1. Update payment method:

   • Go to Settings → Billing
   • Add new payment method
   • Retry payment

2. Check with bank:

   • Verify card is active
   • Check for international transaction blocks
   • Ensure sufficient funds

3. Use alternative method:

   • Try different card
   • Use PayPal
   • Contact support for bank transfer

Out of Credits

Problem: Project suspended due to insufficient credits.

Cause: Usage exceeded prepaid credits.

Solution:

1. Add credits:

   • Go to Settings → Billing
   • Click "Add Credits"
   • Enter amount and payment method

2. Review usage:

   deployxa billing usage --org my-org

3. Set budget alerts:

   • Configure alerts at 50%, 75%, 90%
   • Prevent unexpected charges

4. Optimize usage:

   • Review resource allocation
   • Enable auto-scaling limits
   • Remove unused projects

CLI Issues

Command Not Found

Problem: deployxa: command not found

Cause: CLI not installed or not in PATH.

Solution:

1. Install CLI:

   npm install -g @deployxa/cli

2. Check PATH:

   echo $PATH

3. Use full path:

   ~/.npm-global/bin/deployxa

4. Reinstall:

   npm uninstall -g @deployxa/cli
   npm install -g @deployxa/cli

Authentication Failed

Problem: Error: Authentication failed

Cause: Invalid or expired API token.

Solution:

1. Login again:

   deployxa login

2. Check token:

   deployxa whoami

3. Generate new token:

   • Go to Settings → API Keys
   • Create new API key
   • Use new token

Getting Help

Debugging Steps

1. Check logs:

   deployxa logs --project my-app --follow

2. Verify configuration:

   deployxa project get my-app

3. Test locally:

   • Reproduce issue locally
   • Check environment variables
   • Verify dependencies

4. Check status:

   • Visit status.deployxa.com
   • Check for ongoing incidents

Contact Support

Email: support@deployxa.com

Include:

• Project name/ID
• Deployment ID (if applicable)
• Error messages
• Steps to reproduce
• Expected vs actual behavior

Response Time:

• Free tier: 48 hours
• Pro tier: 24 hours
• Enterprise tier: 4 hours

Community Support

Discord: discord.gg/deployxa

GitHub: github.com/deployxa

Stack Overflow: Tag questions with deployxa

Common Error Codes

Code	Meaning	Solution
400	Bad Request	Check request format
401	Unauthorized	Verify API token
403	Forbidden	Check permissions
404	Not Found	Verify resource exists
429	Rate Limited	Wait and retry
500	Server Error	Contact support
503	Service Unavailable	Check status page

Related Topics

• Getting Started
• API Reference
• CLI Reference
• Monitoring

---

Need Help? Contact support@deployxa.com or join our community Discord.