Troubleshooting Deployments

Encountering deployment issues? Here are solutions to the most common problems.

Build Failures

"Module not found" Error

Symptom: Build fails with Cannot find module 'xyz'

Solution:

1. Ensure the package is in package.json dependencies (not devDependencies)
2. Delete node_modules and reinstall:

   rm -rf node_modules package-lock.json
   npm install

3. Commit updated package-lock.json
4. Redeploy

Build Command Fails

Symptom: npm run build returns error

Solution:

1. Test build locally first:

   npm install
   npm run build

2. Check that your package.json has a build script
3. Verify all build dependencies are listed
4. Check build logs for specific error messages

Out of Memory Error

Symptom: Build fails with "JavaScript heap out of memory"

Solution: Increase Node.js memory limit in your build command:

{
  "scripts": {
    "build": "NODE_OPTIONS='--max-old-space-size=4096' next build"
  }
}

GitHub Connection Issues

"Failed to clone repository"

Symptom: Deployment fails at cloning stage

Solution:

1. Check if Oblien has access to your repository
2. Go to GitHub → Settings → Applications
3. Ensure Oblien has repository access
4. Try reconnecting your GitHub account
5. Check if repository is private and access is granted

Webhook Not Triggering

Symptom: Auto-deploy doesn't work after push

Solution:

1. Check repository webhook settings
2. Go to Repository → Settings → Webhooks
3. Verify Oblien webhook exists and is active
4. Check recent deliveries for errors
5. Try manual redeploy first

Runtime Errors

Application Won't Start

Symptom: Build succeeds but app doesn't start

Solution:

1. Check your start command is correct
2. Verify the port configuration (default: 3000)
3. Ensure your app listens on process.env.PORT:

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

4. Review application startup logs

404 on All Routes

Symptom: Deployment succeeds but all pages show 404

Solution:

For Static Sites:

• Verify output directory is correct
• Check build actually generated files
• Ensure index.html exists in output directory

For Server-Rendered Apps:

• Confirm server mode is selected (not static)
• Check start command is configured
• Verify application is listening on correct port

Missing Environment Variables

Symptom: App deployed but API calls fail

Solution:

1. Environment variables feature coming soon
2. For now, use build-time variables:

   // Next.js
   NEXT_PUBLIC_API_URL=https://api.example.com npm run build

3. Or hardcode production URLs temporarily

Performance Issues

Slow Build Times

Symptom: Builds take longer than expected

Solution:

1. Remove unused dependencies
2. Use cache-friendly package managers
3. Optimize build configuration
4. Consider build caching (coming soon)

Slow Application Response

Symptom: App is slow after deployment

Solution:

1. Enable production mode in build
2. Optimize bundle size
3. Use CDN for static assets
4. Check database/API response times
5. Review application logs for bottlenecks

Framework-Specific Issues

Next.js

Issue: Static export not working

Solution:

1. Ensure next.config.js has:

   module.exports = {
     output: 'export'
   };

2. Set output directory to out instead of .next
3. Don't use SSR/API routes with static export

Issue: Image optimization error

Solution: For static exports, use unoptimized:

// next.config.js
module.exports = {
  images: {
    unoptimized: true
  }
};

React (Create React App)

Issue: Environment variables not working

Solution: Use REACT_APP_ prefix:

// Works
const API_URL = process.env.REACT_APP_API_URL;

// Doesn't work
const API_URL = process.env.API_URL;

Vue/Vite

Issue: Import paths broken in production

Solution: Set correct base path in vite.config.js:

export default {
  base: '/'
};

Checking Deployment Status

Real-Time Build Logs

Watch your deployment progress:

1. Navigate to build page
2. View live streaming logs
3. Check for errors or warnings
4. Note where build fails

Build History

Review previous deployments:

1. Go to your project
2. Click Builds or History
3. Compare successful vs failed builds
4. Check what changed between them

Common Error Messages

"Port already in use"

Solution: Ensure your app uses process.env.PORT:

const port = process.env.PORT || 3000;

"Permission denied"

Solution:

• Don't use ports below 1024
• Ensure file permissions are correct
• Check build scripts don't require sudo

"Build timed out"

Solution:

• Optimize build process
• Remove unnecessary build steps
• Contact support for timeout increases

Still Having Issues?

If you've tried the above solutions and still have problems:

1. Check Build Logs

The logs usually contain the exact error message and stack trace.

2. Test Locally

Run the exact same commands locally:

npm install
npm run build
npm start

3. Search Documentation

Check related docs:

• Configuration
• Best Practices
• Quick Start

4. Common Scenarios

5. Contact Support

Still stuck? Reach out with:

• Deployment ID or URL
• Build logs (copy/paste error messages)
• Steps you've already tried
• Your framework and version

Prevention Tips

Avoid common issues by:

1. Testing locally first - Always build locally before deploying
2. Using .gitignore - Don't commit build artifacts
3. Keeping dependencies updated - Regular npm update
4. Following best practices - See our Best Practices guide
5. Monitoring builds - Watch logs for warnings

Quick Debugging Commands

# Test build locally
npm run build

# Check for missing dependencies
npm ls

# Verify Node.js version
node --version

# Check npm script
npm run

# Clear cache and reinstall
rm -rf node_modules package-lock.json && npm install

Related Resources

• Configuration Guide - Detailed configuration options
• Best Practices - Avoid common pitfalls
• Quick Start - Get started quickly