Troubleshooting Airbase Deployments¶

Comprehensive troubleshooting guide for common Airbase deployment and runtime issues.

How to Use This Guide¶

Finding Your Issue¶

1. Know where it failed - Installation? Build? Deploy? Runtime?
2. Check the Quick Diagnostics section below for a decision tree
3. Jump to the relevant section for detailed troubleshooting
4. Follow the solution steps for your specific issue

Before You Start¶

Gather this information:

• Error messages (full text)
• Command you ran
• Your airbase.json configuration
• Your Dockerfile (first 20 lines)
• Docker version: docker --version
• CLI version: airbase --version

Quick Diagnostics¶

Where did the problem occur?

┌─────────────────────────────────────────┐
│  Where did the failure occur?           │
└─────────────────────────────────────────┘
                    │
        ┌───────────┼───────────┐
        │           │           │
    Installing  Building   Deploying
        CLI       Image        App
        │           │           │
        ↓           ↓           ↓
   Section A   Section B   Section C
                                │
                    ┌───────────┴───────────┐
                    │                       │
              App Deployed              App Running
              But Not Working          But Has Issues
                    │                       │
                    ↓                       ↓
               Section D               Section E
              (Runtime)             (Performance)

Quick Links:

• Section A: Installation & Setup
• Section B: Build Issues
• Section C: Deployment Issues
• Section D: Runtime & Application Issues
• Section E: Performance Issues

Section A: Installation & Setup Issues¶

Problems installing the CLI or setting up your development environment.

Issue A1: CLI Command Not Found¶

Error:

$ airbase --version
zsh: command not found: airbase

Cause: npm global bin directory not in PATH

Solution:

1. Find npm global bin directory:

   npm config get prefix
   

2. Add to PATH in your shell profile:

For bash (~/.bashrc or ~/.bash_profile):

export PATH="$HOME/.local/bin:$PATH"

For zsh (~/.zshrc):

export PATH="$HOME/.local/bin:$PATH"

1. Reload shell:

   source ~/.zshrc  # or ~/.bashrc
   

2. Verify installation:

   airbase --version
   

Alternative: Reinstall with correct permissions:

sudo npm install --global @airbase/airbase-cli@containers

Issue A2: npm Permission Errors¶

Error:

npm ERR! code EACCES
npm ERR! syscall access
npm ERR! path /usr/local/lib/node_modules
npm ERR! errno -13
npm ERR! Error: EACCES: permission denied

Cause: Insufficient permissions to write to global npm directory

Solution:

Use sudo for global installation:

sudo npm install --global @airbase/airbase-cli@containers

Alternative: Fix npm permissions (advanced):

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

Then install without sudo:

npm install --global @airbase/airbase-cli@containers

Issue A3: Docker Not Running¶

Error:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
Is the docker daemon running?

Cause: Docker daemon is not started

Solution (macOS/Windows - Docker Desktop):

1. Open Docker Desktop application
2. Wait for Docker to start (icon appears in menu bar/system tray)
3. Verify Docker is running:

   docker ps
   

Solution (Linux):

sudo systemctl start docker
sudo systemctl enable docker  # Start on boot

Solution (macOS - Colima):

colima start

Verify:

docker ps

Issue A4: Authentication Failed¶

Error:

Error: Authentication failed
Error: Invalid credentials

Cause: Token expired or invalid

Solution:

1. Run airbase login again:

   airbase login
   

2. Open the URL in your browser

3. Confirm authentication
4. Name your token
5. Verify success:

   airbase project list
   

If still failing:

1. Check you're logging in with correct account (TechPass or email)
2. Verify you have access to Airbase Console
3. Try clearing credentials:

   rm ~/.airbaserc
   airbase login
   

Issue A5: Node.js or npm Not Installed¶

Error:

command not found: npm
command not found: node

Cause: Node.js/npm not installed

Solution (macOS - Homebrew):

brew install node

Solution (macOS - Direct Download):

1. Visit https://nodejs.org
2. Download LTS version (.pkg installer)
3. Run installer
4. Verify:

   node --version
   npm --version
   

Solution (Linux - Ubuntu/Debian):

sudo apt update
sudo apt install nodejs npm

Solution (Linux - CentOS/RHEL):

sudo yum install nodejs npm

Section B: Build Issues¶

Problems building your container image.

Issue B1: Dockerfile Not Found¶

Error:

Error: Dockerfile not found
unable to prepare context: unable to evaluate symlinks in Dockerfile path

Cause: No Dockerfile in current directory

Solution:

1. Verify you're in the correct directory:

   ls -la
   

2. Check for Dockerfile:

   ls Dockerfile
   

3. Create Dockerfile if missing - see examples:

4. Node.js Example
5. Python Example
6. Dockerfile Requirements

Issue B2: Permission Denied in Container¶

Error:

Step 5/10 : COPY app.py ./
ERROR: failed to solve: failed to compute cache key: failed to walk /var/lib/docker/...:
lstat ...: permission denied

Cause: Missing --chown=app:app in COPY commands

Solution:

Update Dockerfile to use --chown=app:app:

❌ Wrong:

COPY app.py ./
COPY requirements.txt ./

✅ Correct:

COPY --chown=app:app app.py ./
COPY --chown=app:app requirements.txt ./

Also ensure USER directive:

USER app
CMD ["python", "app.py"]

Issue B3: Build Fails - File Not Found¶

Error:

COPY failed: file not found in build context or excluded by .dockerignore

Cause: File doesn't exist or is excluded by .dockerignore

Solution:

1. Verify file exists:

   ls -la app.py requirements.txt
   

2. Check .dockerignore (if it exists):

   cat .dockerignore
   

3. Remove exclusion or move file to included location

4. Verify file paths in Dockerfile are relative to project root

Issue B4: Base Image Pull Failed¶

Error:

failed to solve with frontend dockerfile.v0: failed to create LLB definition:
failed to pull base image: gdssingapore/airbase:node-22: not found

Cause: Wrong base image name or network issue

Solution:

1. Check base image name spelling:

   # ❌ Wrong
   FROM gdssingapore/airbase:node-2.2
   
   # ✅ Correct
   FROM gdssingapore/airbase:node-22
   

2. Verify available images at Base Images Catalog

3. Check Docker Hub connectivity:

   docker pull gdssingapore/airbase:node-22
   

4. Retry build if network issue

Issue B5: npm install or pip install Fails¶

Error (Node.js):

npm ERR! code ENOENT
npm ERR! syscall open
npm ERR! path /app/package.json
npm ERR! errno -2
npm ERR! enoent ENOENT: no such file or directory, open '/app/package.json'

Error (Python):

ERROR: Could not open requirements file: [Errno 2] No such file or directory: 'requirements.txt'

Cause: Files copied in wrong order or not copied at all

Solution (Node.js):

FROM gdssingapore/airbase:node-22-builder AS builder
WORKDIR /app
# Copy package files FIRST
COPY --chown=app:app package.json package-lock.json* ./
# THEN run install
RUN npm install
# THEN copy application files
COPY --chown=app:app . ./

Solution (Python):

FROM gdssingapore/airbase:python-3.13
# Copy requirements FIRST
COPY --chown=app:app requirements.txt ./
# THEN run install
RUN pip install -r requirements.txt
# THEN copy application files
COPY --chown=app:app . ./

Issue B6: Build Timeout or Too Slow¶

Problem: Build takes >10 minutes or times out

Cause: Large files, no layer caching, or slow network

Solution:

1. Add .dockerignore to exclude unnecessary files:

# .dockerignore
node_modules
__pycache__
.git
.env
*.log
.DS_Store

1. Use multi-stage builds to reduce final image size:

FROM gdssingapore/airbase:node-22-builder AS builder
# ... build steps ...

FROM gdssingapore/airbase:node-22
COPY --from=builder /app/dist ./dist

1. Order commands for better caching:
2. Copy dependency files first
3. Run install

4. Copy application code last

5. Check network connection

Issue B7: Port Already in Use (Local Testing)¶

Error:

Error starting userland proxy: listen tcp4 0.0.0.0:3000: bind: address already in use

Cause: Port 3000 already in use by another process

Solution:

1. Find process using the port:

macOS/Linux:

lsof -i :3000

Windows:

netstat -ano | findstr :3000

1. Stop the process or use different port:

   docker run -p 3001:3000 -e PORT=3000 your-image
   

Section C: Deployment Issues¶

Problems deploying your built container to Airbase.

Issue C1: airbase.json Not Found¶

Error:

Error: airbase.json not found
Please run 'airbase configure' or create airbase.json manually

Cause: No airbase.json in current directory

Solution:

1. Create airbase.json using CLI (recommended):

   airbase configure
   

2. Or create manually:

   {
     "framework": "container",
     "handle": "team/project",
     "port": 3000,
     "instanceType": "nano"
   }
   

3. Verify file exists:

   cat airbase.json
   

Issue C2: Invalid Project Handle¶

Error:

Error: Project not found: team/project
Error: Invalid project handle

Cause: Project doesn't exist or you don't have access

Solution:

1. Log in to Airbase Console

2. Navigate to your project

3. Copy the exact project handle (format: team-name/project-name)

4. Update airbase.json:

   {
     "handle": "correct-team/correct-project"
   }
   

5. Or run airbase configure to select from available projects

Common mistakes:

• ❌ Using uppercase: Team/Project
• ❌ Using spaces: team name/project
• ❌ Using underscores: team_name/project
• ✅ Correct format: team-name/project-name

Issue C3: Directory Name Contains Uppercase or Spaces¶

Error:

Error: Invalid directory name
Directory names must be lowercase with no spaces

Cause: Project directory has uppercase letters or spaces

Solution:

Rename directory:

# Wrong
cd MyProject
cd "My Project"

# Correct - rename
cd ..
mv MyProject myproject
mv "My Project" my-project
cd myproject

Issue C4: Port Mismatch¶

Problem: Deployment succeeds but application not accessible

Cause: Port in airbase.json doesn't match application's listening port

Solution:

Ensure consistency between airbase.json and application code:

airbase.json:

{
  "port": 3000
}

Application (Node.js):

const PORT = process.env.PORT || 3000;  // Must match
app.listen(PORT, '0.0.0.0');

Application (Python):

port = int(os.environ.get('PORT', 3000))  # Must match
app.run(host='0.0.0.0', port=port)

Issue C5: Deployment Hangs or Times Out¶

Problem: airbase container deploy hangs indefinitely

Cause: Network issue, large image, or platform issue

Solution:

1. Check your network connection

2. Verify image was built successfully:

   docker images | grep local.airbase.sg
   

3. Try deploying again with --yes flag:

   airbase container deploy --yes
   

4. If still hanging, check Airbase Console for deployment status

5. Try deploying to staging first:

   airbase container deploy --yes staging
   

Issue C6: Invalid JSON in airbase.json¶

Error:

Error: Failed to parse airbase.json
SyntaxError: Unexpected token } in JSON at position 85

Cause: Malformed JSON (missing comma, trailing comma, etc.)

Solution:

1. Validate JSON syntax:

   cat airbase.json | python3 -m json.tool
   

2. Common mistakes:

❌ Trailing comma:

{
  "port": 3000,
  "instanceType": "nano",  ← Remove trailing comma
}

❌ Missing comma:

{
  "port": 3000  ← Add comma
  "instanceType": "nano"
}

✅ Correct:

{
  "port": 3000,
  "instanceType": "nano"
}

1. Or regenerate with CLI:

   airbase configure
   

Issue C7: Wrong Environment Deployed¶

Problem: Deployed to wrong environment (e.g., production instead of staging)

Cause: Didn't specify environment or used wrong command

Solution:

Always specify environment explicitly:

# Deploy to staging
airbase container deploy --yes staging

# Deploy to development
airbase container deploy --yes development

# Deploy to production (default)
airbase container deploy --yes

To fix:

1. Deploy to correct environment:

   airbase container deploy --yes staging
   

2. Destroy deployment from wrong environment:

   # Destroy from production (default environment)
   airbase container destroy
   
   # Or destroy from a specific environment
   airbase container destroy production
   

Section D: Runtime & Application Issues¶

Application deployed successfully but not working correctly.

Issue D1: 502 Bad Gateway¶

Error: Browser shows "502 Bad Gateway"

Cause: Application not listening on correct port or crashed

Solution:

1. Check Airbase Console logs for errors

2. Verify PORT environment variable usage:

Node.js:

const PORT = process.env.PORT || 3000;
app.listen(PORT, '0.0.0.0');  // Must bind to 0.0.0.0

Python:

port = int(os.environ.get('PORT', 3000))
app.run(host='0.0.0.0', port=port)  # Must bind to 0.0.0.0

1. Ensure port in airbase.json matches application port

2. Check application starts successfully (view logs in Console)

Issue D2: Application Not Accessible¶

Problem: Deployment successful but URL returns error

Cause: Multiple possible causes

Solution - Check URL format:

Correct URL format:

# Production (default environment)
https://PROJECT-NAME.app.tc1.airbase.sg

# Staging environment
https://staging--PROJECT-NAME.app.tc1.airbase.sg

# Custom environment
https://ENV-NAME--PROJECT-NAME.app.tc1.airbase.sg

Common mistakes:

• ❌ Using team name: https://team-name.app.tc1.airbase.sg
• ❌ Wrong separator: https://staging-PROJECT-NAME.app.tc1.airbase.sg
• ✅ Correct: https://staging--PROJECT-NAME.app.tc1.airbase.sg (note double dash)

Solution - Check logs:

1. Go to Airbase Console
2. Navigate to your project
3. Select environment
4. View logs for errors
5. Fix errors in code and redeploy

Issue D3: JavaScript Not Working (CSP Violations)¶

Symptoms:

• Buttons don't respond
• Forms don't submit
• Dynamic content doesn't load
• Browser console shows CSP errors

Cause: Content Security Policy violations

Solution:

1. Open browser console (F12)

2. Look for red CSP errors:

   Refused to execute inline script because it violates CSP...
   

3. Follow Troubleshoot CSP Violations guide

4. Fix violations:

5. Move inline scripts to external files
6. Remove inline event handlers

7. Remove eval() usage

8. Test locally first: Test CSP Locally

9. Redeploy after fixing

Issue D4: Environment Variables Not Loading¶

Problem: process.env.DATABASE_URL is undefined

Cause: .env file issues or wrong environment

Solution:

1. Check .env file exists and has correct naming:

.env           → Production (default)
.env.staging   → Staging environment
.env.dev       → Dev environment

1. Verify .env file format:

# ✅ Correct
DATABASE_URL=postgresql://...
API_KEY=secret123

# ❌ Wrong - no spaces around =
DATABASE_URL = postgresql://...

1. Ensure .env file is in project root (same directory as airbase.json)

2. Verify you deployed to correct environment:

   airbase container deploy --yes staging  # Uses .env.staging
   

3. Check environment variables in application code:

Node.js:

const dbUrl = process.env.DATABASE_URL;
if (!dbUrl) {
  console.error('DATABASE_URL not set');
}

Python:

import os
db_url = os.environ.get('DATABASE_URL')
if not db_url:
    print('DATABASE_URL not set')

See: Set Environment Variables

Issue D5: Application Crashes Immediately¶

Problem: Deployment succeeds but application crashes

Solution:

1. Check logs in Airbase Console:
2. Go to Console → Project → Environment → Logs

3. Look for error messages

4. Common crash causes:

Missing dependencies:

Error: Cannot find module 'express'
ModuleNotFoundError: No module named 'flask'

Fix: Add to package.json or requirements.txt

Permission errors:

EACCES: permission denied, open '/app/data.json'

Fix: Ensure --chown=app:app in Dockerfile

Port binding errors:

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

Fix: Check application listens on process.env.PORT

Syntax errors:

SyntaxError: Unexpected token

Fix: Test locally first, fix syntax

1. Test locally with Docker:

   docker run -p 3000:3000 -e PORT=3000 local.airbase.sg/your-app:tag
   

2. Fix issues and redeploy:

   airbase container build
   airbase container deploy --yes staging
   

Issue D6: Static Assets Not Loading¶

Problem: HTML loads but CSS/JS/images don't load

Cause: Wrong paths or not copied to container

Solution:

1. Check paths in HTML:

❌ Wrong - absolute paths:

<link rel="stylesheet" href="/static/style.css">
<script src="/static/app.js"></script>

✅ Correct - relative paths:

<link rel="stylesheet" href="./style.css">
<script src="./app.js"></script>

Or configure web server to serve /static directory

1. Verify files copied in Dockerfile:

COPY --chown=app:app ./public ./public
COPY --chown=app:app ./static ./static

1. Check Express static middleware (Node.js):

app.use('/static', express.static('public'));

1. Check Flask static folder (Python):

app = Flask(__name__, static_folder='static', static_url_path='/static')

Issue D7: Database Connection Failed¶

Problem: Can't connect to external database

Cause: Wrong connection string or network issue

Solution:

1. Verify connection string in .env:

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

1. Check database host is accessible from Airbase:
2. Database must be publicly accessible or on same network

3. Cannot connect to localhost from container

4. Use correct host:

❌ Wrong:

DATABASE_URL=postgresql://localhost:5432/db

✅ Correct:

DATABASE_URL=postgresql://db.example.com:5432/db
DATABASE_URL=postgresql://10.0.0.5:5432/db

1. Check database credentials

2. Test connection in application startup:

// Node.js
const client = new Client({ connectionString: process.env.DATABASE_URL });
client.connect()
  .then(() => console.log('Connected to database'))
  .catch(err => console.error('Database connection failed:', err));

Issue D8: CORS Errors¶

Problem: API calls from frontend fail with CORS errors

Error in browser console:

Access to fetch at 'https://api.example.com' from origin 'https://myapp.app.tc1.airbase.sg'
has been blocked by CORS policy

Cause: Backend doesn't allow requests from your domain

Solution:

Add CORS headers in your backend:

Node.js/Express:

const cors = require('cors');

app.use(cors({
  origin: 'https://myapp.app.tc1.airbase.sg',
  credentials: true
}));

Python/Flask:

from flask_cors import CORS

app = Flask(__name__)
CORS(app, origins=['https://myapp.app.tc1.airbase.sg'])

Python/FastAPI:

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=['https://myapp.app.tc1.airbase.sg'],
    allow_credentials=True,
    allow_methods=['*'],
    allow_headers=['*'],
)

Section E: Performance Issues¶

Application works but has performance problems.

Issue E1: Out of Memory Errors¶

Error in logs:

JavaScript heap out of memory
MemoryError
killed (signal 9)

Cause: Instance too small for application

Solution:

Upgrade instance type in airbase.json:

{
  "framework": "container",
  "handle": "team/project",
  "port": 3000,
  "instanceType": "b.small"  ← Changed from "nano"
}

Redeploy:

airbase container deploy --yes

Instance types:

See: Instance Types

Issue E2: Application Running Slow¶

Problem: Pages load slowly or timeout

Cause: Under-resourced instance or inefficient code

Solution:

1. Upgrade instance type:

{
  "instanceType": "b.small"
}

1. Check logs for performance issues:
2. Database query times
3. API response times

4. Memory usage

5. Optimize application:

6. Add database indexes
7. Cache expensive operations
8. Optimize queries

9. Reduce bundle size (frontend)

10. Monitor in Airbase Console:

11. CPU usage
12. Memory usage
13. Response times

Issue E3: High CPU Usage¶

Problem: Application using 100% CPU

Cause: Infinite loop, inefficient code, or too many requests

Solution:

1. Check logs for errors

2. Review recent code changes

3. Look for:

4. Infinite loops
5. Recursive functions without base case
6. Unoptimized algorithms

7. Memory leaks

8. Upgrade instance if needed:

   {
     "instanceType": "b.small"
   }
   

Issue E4: Container Restarting Frequently¶

Problem: Application keeps restarting (check Console)

Cause: Crashes, health check failures, or memory issues

Solution:

1. Check logs for crash reason

2. Common causes:

3. Out of memory → Upgrade instance
4. Uncaught exceptions → Add error handling

5. Port binding issues → Check PORT usage

6. Add error handling:

Node.js:

process.on('uncaughtException', (err) => {
  console.error('Uncaught exception:', err);
});

process.on('unhandledRejection', (err) => {
  console.error('Unhandled rejection:', err);
});

Python:

import logging
logging.basicConfig(level=logging.ERROR)

try:
    # Application code
except Exception as e:
    logging.error(f'Application error: {e}')

Getting Additional Help¶

Check Airbase Console Logs¶

Logs are your best friend for troubleshooting:

1. Go to Airbase Console
2. Select your project
3. Select environment
4. View logs
5. Look for error messages

See: View Application Logs

Review Documentation¶

For specific issues:

• CSP problems: Troubleshoot CSP Violations
• Environment variables: Set Environment Variables
• Dockerfile issues: Dockerfile Requirements
• Configuration: airbase.json Reference
• Deployment: Build and Deploy

Test Locally First¶

Before deploying, test locally:

1. Test CSP compliance: Test CSP Locally
2. Test with Docker:

   airbase container build
   docker run -p 3000:3000 -e PORT=3000 local.airbase.sg/your-app:tag
   

3. Fix issues locally before deploying

Common Resolution Steps¶

For most issues:

1. Check logs in Airbase Console
2. Test locally with Docker
3. Fix the issue
4. Rebuild container:

   airbase container build
   

5. Deploy to staging first:

   airbase container deploy --yes staging
   

6. Verify fix in staging
7. Deploy to production:

   airbase container deploy --yes
   

Still Stuck?¶

If you've tried everything and still having issues:

1. Gather information:
2. Full error message
3. CLI version: airbase --version
4. Docker version: docker --version
5. Your airbase.json
6. Relevant Dockerfile sections

7. Console log output

8. Contact support with the above information

9. Check for platform issues:

10. Visit Airbase Console for status updates
11. Check with team members if they're experiencing similar issues

Troubleshooting Checklist¶

Use this checklist when troubleshooting:

Pre-deployment Checks¶

• Docker is running: docker ps
• CLI is installed: airbase --version
• Authenticated: airbase project list works
• airbase.json exists and is valid JSON
• Dockerfile exists
• Directory name is lowercase, no spaces
• All COPY commands use --chown=app:app
• USER app directive present in Dockerfile

Build Checks¶

• Build completes successfully
• No permission errors during build
• Dependencies install correctly
• Base image name is correct

Deployment Checks¶

• Project handle in airbase.json is correct
• Port matches between airbase.json and application
• .env file exists (if using environment variables)
• Deploying to correct environment

Post-deployment Checks¶

• Application URL is correct format
• No CSP errors in browser console
• Logs in Console show no errors
• Application responds on expected URL
• All features work as expected

See Also¶

• How-To: Build and Deploy - Deployment workflow
• How-To: Troubleshoot CSP Violations - Fix CSP errors
• How-To: Test CSP Locally - Test before deploying
• How-To: Set Environment Variables - Configure environment
• How-To: View Logs - Debug with logs
• Reference: CLI Commands - Command reference
• Reference: Dockerfile Requirements - Docker specs
• Reference: airbase.json Configuration - Config reference
• Tutorial: Getting Started - First deployment

Summary¶

Remember:

• ✅ Identify where the failure occurred (install, build, deploy, or runtime)
• ✅ Check logs first - they usually contain the answer
• ✅ Test locally before deploying
• ✅ Fix issues in staging before production
• ✅ Use the specific troubleshooting guides for CSP, environment variables, etc.

Most common issues:

1. CSP violations → Troubleshoot CSP
2. Port mismatch → Check airbase.json vs application code
3. Permission errors → Add --chown=app:app to Dockerfile
4. Environment variables not loading → Check .env file naming
5. Out of memory → Upgrade instance type to b.small

Quick wins:

• Always check browser console (F12) for errors
• Always check Airbase Console logs
• Always test locally before deploying
• Always deploy to staging first

Happy troubleshooting! 🔧