Connection Troubleshooting

This guide helps you diagnose and resolve common connection issues with your APSO backend.

Quick Diagnostics

Run these checks first:

# 1. Is the server running?
curl http://localhost:3001/health
 
# 2. Can you reach the database?
psql $DATABASE_URL -c "SELECT 1"
 
# 3. Is auth working?
curl -X POST http://localhost:3001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password"}'

Connection Errors

ECONNREFUSED

Error: connect ECONNREFUSED 127.0.0.1:3001

Cause: Server is not running or wrong port.

Solutions:

1. Start the server: npm run dev
2. Check the port in your .env: PORT=3001
3. Verify nothing else is using the port: lsof -i :3001

ENOTFOUND

Error: getaddrinfo ENOTFOUND api.example.com

Cause: DNS resolution failed.

Solutions:

1. Check the URL spelling
2. Verify DNS is working: nslookup api.example.com
3. Try using IP address instead

ETIMEDOUT

Error: connect ETIMEDOUT

Cause: Server unreachable or too slow.

Solutions:

1. Check network connectivity
2. Verify firewall rules
3. Check if server is overloaded

Authentication Errors

401 Unauthorized

{
  "statusCode": 401,
  "message": "Unauthorized"
}

Possible causes:

• Missing auth header
• Expired token
• Invalid token

Solutions:

# Check if token is included
curl -v http://localhost:3001/api/v1/projects
 
# Refresh your token
curl -X POST http://localhost:3001/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "your-refresh-token"}'

403 Forbidden

{
  "statusCode": 403,
  "message": "Forbidden"
}

Possible causes:

• Accessing another organization’s data
• Missing organization context
• Insufficient permissions

Solutions:

1. Verify you’re accessing your own organization’s resources
2. Check X-Organization-Id header if multi-tenant
3. Verify user has required role/permissions

Invalid Token Format

{
  "statusCode": 401,
  "message": "Invalid token"
}

Solutions:

1. Ensure format is Bearer <token> (with space)
2. Check token isn’t truncated
3. Verify you’re using the access token, not refresh token

Database Errors

Connection Refused

Error: connect ECONNREFUSED 127.0.0.1:5432

Solutions:

# Check if PostgreSQL is running
docker ps | grep postgres
# or
pg_isready -h localhost -p 5432
 
# Start PostgreSQL
docker start apso-postgres
# or
brew services start postgresql

Authentication Failed

Error: password authentication failed for user "apso"

Solutions:

1. Verify DATABASE_URL credentials
2. Check pg_hba.conf authentication rules
3. Reset password:

docker exec -it apso-postgres psql -U postgres -c \
  "ALTER USER apso WITH PASSWORD 'newpassword';"

Database Does Not Exist

Error: database "apso_dev" does not exist

Solutions:

# Create the database
docker exec -it apso-postgres createdb -U postgres apso_dev
 
# Or run setup
npm run db:setup

Too Many Connections

Error: too many connections for role "apso"

Solutions:

1. Reduce connection pool size in .apsorc
2. Increase PostgreSQL max_connections
3. Use a connection pooler (PgBouncer)

{
  "database": {
    "pool": {
      "max": 10
    }
  }
}

Request Errors

400 Bad Request

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [...]
}

Solutions:

1. Check required fields are present
2. Verify data types match schema
3. Review validation error messages

404 Not Found

{
  "statusCode": 404,
  "message": "Not found"
}

Possible causes:

• Resource doesn’t exist
• Wrong endpoint URL
• Resource is soft-deleted
• Resource belongs to different organization

Solutions:

1. Verify the ID is correct
2. Check the endpoint path
3. Confirm resource exists in database

422 Unprocessable Entity

{
  "statusCode": 422,
  "message": "Unprocessable Entity",
  "errors": [
    {"field": "email", "message": "Email already exists"}
  ]
}

Solutions:

1. Review specific field errors
2. Check unique constraint violations
3. Validate enum values

CORS Errors

Browser Console Error

Access to XMLHttpRequest at 'http://localhost:3001' has been blocked by CORS policy

Solutions:

1. Configure CORS in your APSO server:

// src/main.ts
app.enableCors({
  origin: ['http://localhost:3000'],
  credentials: true,
});

2. Or configure in .apsorc:

{
  "api": {
    "cors": {
      "origin": ["http://localhost:3000"],
      "credentials": true
    }
  }
}

SSL/TLS Errors

Certificate Errors

Error: unable to verify the first certificate

Solutions:

1. For development, add ?sslmode=disable (not for production)
2. Install proper SSL certificates
3. Use NODE_TLS_REJECT_UNAUTHORIZED=0 for testing only

Performance Issues

Slow Responses

Diagnostics:

# Check query performance
DEBUG=typeorm:query npm run dev
 
# Profile endpoint
time curl http://localhost:3001/api/v1/projects

Solutions:

1. Add database indexes
2. Reduce include depth
3. Implement pagination
4. Enable query caching

Timeout Errors

Error: Request timeout

Solutions:

1. Increase client timeout
2. Optimize slow queries
3. Add indexes to frequently queried fields
4. Consider pagination for large datasets

Debug Mode

Enable verbose logging:

# Environment variable
DEBUG=* npm run dev
 
# Or in .env
DEBUG=apso:*,typeorm:query

Getting Help

If you’re still stuck:

1. Check server logs for detailed error messages
2. Review the FAQ
3. Search the GitHub issues 
4. Join the Discord community 

Related

• Database Setup →
• Testing Your API →
• Local Development →