Troubleshooting

Solutions to common issues when working with APSO.

CLI Issues

`apso: command not found`

Cause: CLI not installed or not in PATH.

Solution:


# Reinstall globally
npm install -g @apso/cli
 
# Verify installation
which apso
apso --version

If using a version manager (nvm, fnm), ensure you’re in the correct Node version.

`Error: Invalid schema`

Cause: Syntax error in .apsorc file.

Solution:


# Validate your schema
apso validate
 
# Common issues:
# - Missing commas between fields
# - Invalid field types
# - Duplicate entity names
# - Missing required properties

`Error: Could not authenticate`

Cause: Invalid or expired authentication token.

Solution:


# Re-authenticate
apso logout
apso login
 
# Check credentials
apso whoami

Generation hangs or is slow

Cause: Large schema or network issues.

Solution:


# Check schema size
cat .apsorc | wc -l
 
# Try with verbose logging
DEBUG=* apso generate
 
# For very large schemas, use:
apso generate --entity Project  # Generate single entity

Database Issues

`Error: Connection refused`

Cause: Database server not running or inaccessible.

Solution:


# Check if PostgreSQL is running
pg_isready -h localhost -p 5432
 
# For Docker:
docker ps | grep postgres
 
# Verify connection string
psql $DATABASE_URL -c "SELECT 1"

`Error: Authentication failed`

Cause: Wrong credentials in DATABASE_URL.

Solution:


# Check format
# postgresql://user:password@host:port/database
 
# URL-encode special characters in password
# @ → %40, : → %3A, / → %2F

`Error: Database does not exist`

Cause: Database hasn’t been created.

Solution:


# Create database
createdb your_database_name
 
# Or via psql
psql -c "CREATE DATABASE your_database_name"

`Error: Relation does not exist`

Cause: Migrations haven’t been run.

Solution:


# Run pending migrations
npm run migration:run
 
# Check migration status
npm run migration:show

`Error: Too many connections`

Cause: Connection pool exhausted.

Solution:


// Reduce pool size in database config
{
  extra: {
    max: 10,  // Reduce from default 20
  }
}

Or use PgBouncer for connection pooling.

Build & Runtime Issues

`Error: Cannot find module`

Cause: Dependencies not installed or build incomplete.

Solution:


# Clean install
rm -rf node_modules
npm install
 
# Rebuild
npm run build

TypeScript compilation errors

Cause: Type mismatches in custom code.

Solution:


# Check types
npx tsc --noEmit
 
# Common fixes:
# - Import correct types from entities
# - Check optional field handling
# - Verify DTO property types

`Error: Port already in use`

Cause: Another process using the port.

Solution:


# Find process using port
lsof -i :3001
 
# Kill it
kill -9 <PID>
 
# Or use different port
PORT=3002 npm run dev

Hot reload not working

Cause: File watcher issues.

Solution:


# Increase file watcher limit (Linux)
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
 
# Or restart with clean slate
npm run dev -- --watch

API Issues

`401 Unauthorized`

Cause: Missing or invalid authentication token.

Solution:


# Check token is being sent
curl -v -H "Authorization: Bearer <token>" http://localhost:3001/api/v1/projects
 
# Verify token format and expiration
# JWT tokens should have: sub, organizationId, exp

`403 Forbidden`

Cause: User lacks permission for the resource.

Solution:


// Check organization scoping
// Ensure user.organizationId matches resource.organizationId
 
// Check roles if using RBAC
// Verify user has required role

`404 Not Found`

Cause: Resource doesn’t exist or wrong endpoint.

Solution:


# Verify endpoint exists
curl http://localhost:3001/api/v1
 
# Check route registration in controller
# Verify ID format (UUID vs integer)

`422 Validation Error`

Cause: Request body fails validation.

Solution:


# Check required fields
# Verify field types match DTO
# Check field length constraints
# Review error message details in response

`500 Internal Server Error`

Cause: Unhandled exception in application.

Solution:


# Check server logs
npm run dev  # Development logs
 
# Enable verbose logging
LOG_LEVEL=debug npm run dev
 
# Check stack trace for specific error

Deployment Issues

Container won’t start

Cause: Missing environment variables or configuration.

Solution:


# Check env vars
docker run --env-file .env.production my-api printenv
 
# Verify all required vars are set:
# - DATABASE_URL
# - JWT_SECRET
# - NODE_ENV
 
# Check container logs
docker logs <container_id>

Health check failing

Cause: Application not ready or database unavailable.

Solution:


# Test health endpoint manually
curl http://localhost:3001/health
 
# Check database connectivity from container
docker exec <container_id> pg_isready -h <db_host>
 
# Increase health check start period
healthcheck:
  start_period: 30s

Slow cold start

Cause: Large application or slow database connection.

Solution:


// Lazy load heavy modules
import { Module } from '@nestjs/common';
 
@Module({
  imports: [
    TypeOrmModule.forRootAsync({
      // Async configuration for faster startup
    }),
  ],
})

SSL/TLS errors

Cause: Certificate issues or misconfiguration.

Solution:


// For production database with SSL
{
  ssl: {
    rejectUnauthorized: true,
    ca: process.env.DATABASE_CA_CERT,
  }
}
 
// For development (not recommended for production)
{
  ssl: {
    rejectUnauthorized: false,
  }
}

Performance Issues

Slow API responses

Diagnosis:


# Enable query logging
LOG_LEVEL=debug npm run dev
 
# Check for:
# - N+1 queries (many similar queries)
# - Missing indexes
# - Large result sets

Solutions:


// Add eager loading
.find({ relations: ['tasks'] })
 
// Add indexes to entity
@Index(['organizationId'])
 
// Add pagination
.take(20).skip(offset)

High memory usage

Diagnosis:


# Monitor memory
node --expose-gc --inspect dist/main.js

Solutions:


// Stream large results
const queryRunner = this.dataSource.createQueryRunner();
const stream = await queryRunner.stream('SELECT * FROM large_table');
 
// Limit result sizes
.take(1000)

Getting Help

If these solutions don’t resolve your issue:

Check GitHub Issues
Ask in Discord
Email support@apso.cloud with:
- APSO version
- Error message and stack trace
- Steps to reproduce
- Relevant configuration (sanitized)