Troubleshooting Guide

Solutions to common issues when deploying applications on Flux

Deployment Failed

Error: Image not found or pull access denied

Symptoms:

  • •Deployment shows 'Failed to pull image'
  • •Error: repository does not exist

Solutions:

  • Verify your Docker image exists on Docker Hub
  • Ensure the image is public (Flux cannot pull private images without credentials)
  • Check for typos in your repotag (format: username/imagename:tag)
  • Try pulling the image locally: docker pull yourimage:tag
Correct repotag formatjson
{
  "repotag": "username/app:latest",  ✓ Correct
  // NOT "username:app:latest" or "app:latest"
}

Error: Invalid deployment specification

Symptoms:

  • •JSON validation error
  • •Missing required fields error

Solutions:

  • Validate your JSON syntax (use jsonlint.com)
  • Ensure all required fields are present: version, name, repotag, cpu, ram, hdd
  • Check that version is 4 or higher for compose deployments
  • Verify numeric values are numbers, not strings
Common mistakesjson
{
  "cpu": "1.0",      // ❌ Wrong - should be number
  "cpu": 1.0,        // ✓ Correct

  "ram": "2000",     // ❌ Wrong
  "ram": 2000,       // ✓ Correct

  "port": 80,            // External port users access
  "containerPort": 3000  // Port your app listens on internally
}

Error: Port not within system limits 0-65535

Symptoms:

  • •Container Port XXXXX is not within system limits
  • •Invalid port number error
  • •Port validation failed

Solutions:

  • Ensure all port numbers are between 0 and 65535
  • Check both 'port' and 'containerPort' values
  • For multi-port apps, validate each port in the ports array
  • Common mistake: typing extra digits (e.g., 69420 instead of 6942)
Port validationjson
{
  // ❌ WRONG - Port too high
  "port": 69420,
  "containerPort": 69420,

  // ✓ CORRECT - Within valid range
  "port": 6942,
  "containerPort": 6942,

  // Valid port range: 0-65535
  // Common ports:
  // - 80 (HTTP)
  // - 443 (HTTPS)
  // - 3000 (Node.js dev)
  // - 8080 (Alternative HTTP)
  // - 5432 (PostgreSQL)
}

Application Not Starting

Container keeps restarting

Symptoms:

  • •App status shows restarting
  • •Container crashes immediately

Solutions:

  • Check that your app is listening on 0.0.0.0, not localhost
  • Verify the PORT environment variable matches your containerPort
  • Ensure your app doesn't exit immediately (add blocking code)
  • Check application logs in Applications → Management → (your app) → Logs Management
Listen on correct interfacejavascript
// ❌ Wrong - only listens on localhost
app.listen(3000, 'localhost')

// ✓ Correct - listens on all interfaces
app.listen(3000, '0.0.0.0')

// ✓ Also correct - defaults to 0.0.0.0
app.listen(3000)

Application exits immediately

Symptoms:

  • •Container runs but exits with code 0
  • •No error messages but app doesn't stay running

Solutions:

  • Your app must have a long-running process (web server, event loop, etc.)
  • Don't use one-off scripts - they will exit after completion
  • For Node.js: ensure you have app.listen() or similar blocking code
  • For Python: use flask.run() or equivalent server

Missing environment variables

Symptoms:

  • •App crashes with undefined variable errors
  • •Database connection failures

Solutions:

  • Add all required environment variables to environmentParameters in your spec
  • Check variable names for typos
  • Ensure sensitive values are properly set
  • Use defaults in your app code for non-critical variables
Environment variables in specjson
{
  "environmentParameters": [
    "NODE_ENV=production",
    "DB_HOST=fluxpostgres_myapp",
    "DB_PORT=5432",
    "API_KEY=your_key_here"
  ]
}

Domain Not Working

Flux domain not accessible (*.app.runonflux.io)

Symptoms:

  • •Site not found or connection timeout
  • •DNS resolution fails

Solutions:

  • Wait 2-5 minutes after deployment for DNS propagation
  • Verify deployment is running and healthy
  • Check the correct domain format: appname.app.runonflux.io
  • For multi-component: componentname-appname.app.runonflux.io
  • Try accessing with port number if using non-standard port

Custom domain not working

Symptoms:

  • •Custom domain shows 'Site not found'
  • •DNS doesn't resolve
  • •Connection refused

Solutions:

  • Wait up to 48 hours for DNS propagation
  • Verify CloudFlare CNAME record is correct
  • Ensure proxy (orange cloud) is enabled in CloudFlare
  • Check CNAME target: appname.app.runonflux.io (not just appname)
  • Try accessing the Flux domain directly first to ensure app is running
Correct CNAME setuptext
Type: CNAME
Name: app (or @ for root)
Target: myapp.app.runonflux.io  ✓ Include .app.
Proxy: ON (orange cloud)

Database Connection Issues

Cannot connect to database component

Symptoms:

  • •Connection timeout
  • •ENOTFOUND or DNS error
  • •Connection refused

Solutions:

  • Use Flux internal DNS: flux{componentname}_{appname}
  • Verify database component is running and healthy
  • Check database is listening on correct port (5432 for PostgreSQL, 3306 for MySQL)
  • Ensure both components are in the same app deployment
  • Wait for database to fully initialize (30-60 seconds)
Correct database connectionjavascript
// ❌ Wrong
const db = new Pool({
  host: 'postgres.app.runonflux.io',  // External domain won't work
  port: 5432
});

// ✓ Correct - using internal DNS
const db = new Pool({
  host: 'fluxpostgres_myapp',  // Internal DNS pattern
  port: 5432
});

Database authentication failed

Symptoms:

  • •Password authentication failed
  • •Access denied for user

Solutions:

  • Verify credentials in environment variables match database component
  • Check for typos in username/password
  • Ensure password doesn't contain special characters that need escaping
  • For PostgreSQL: wait for database to fully initialize before connecting

Port Not Accessible

Cannot access application port

Symptoms:

  • •Connection refused on port
  • •Port not responding

Solutions:

  • Ensure containerPort matches the port your app actually listens on
  • Check app is listening on 0.0.0.0, not localhost
  • Verify port is EXPOSE'd in Dockerfile
  • For non-standard ports: access via domain:port format
  • External port can be different from container port (Flux handles routing)
Port configurationjson
{
  "port": 80,              // External port users access
  "containerPort": 3000    // Port your app listens on inside container
}

// App must listen on containerPort (3000)
// Users access via port (80)

Need to expose multiple ports

Symptoms:

  • •Need separate ports for app and admin panel
  • •Multiple services on one container
  • •Want to expose metrics endpoint on different port

Solutions:

  • Any app can expose multiple ports using the ports array in the spec
  • Add additional port mappings to your deployment specification
  • Each port can have different external and internal mapping
  • Alternative: deploy separate components for completely different services
Multiple ports configurationjson
{
  "name": "myapp",
  "ports": [
    { "containerPort": 8080, "port": 80 },      // Main web interface
    { "containerPort": 9090, "port": 9090 },    // Admin panel
    { "containerPort": 9100, "port": 9100 }     // Metrics endpoint
  ],
  "cpu": 2.0,
  "ram": 4000,
  "hdd": 20
}

SSL/TLS Errors

SSL certificate warnings

Symptoms:

  • •Browser shows 'Not Secure'
  • •Certificate error
  • •Mixed content warnings

Solutions:

  • Ensure CloudFlare proxy is enabled (orange cloud)
  • Set SSL/TLS mode to 'Full' in CloudFlare
  • Enable 'Always Use HTTPS' in CloudFlare
  • Enable 'Automatic HTTPS Rewrites' to fix mixed content
  • Wait a few minutes for certificate provisioning

Redirect loop (too many redirects)

Symptoms:

  • •ERR_TOO_MANY_REDIRECTS
  • •Page keeps redirecting

Solutions:

  • Change CloudFlare SSL/TLS mode from 'Flexible' to 'Full'
  • Don't force HTTPS redirects in your application code
  • Let CloudFlare handle HTTPS redirection

Storage/Volume Issues

Data not persisting between restarts

Symptoms:

  • •Uploads/data lost after restart
  • •Database data disappears

Solutions:

  • Add containerData field to your spec with the appropriate volume prefix
  • Choose the right prefix: s:/ (single node), r:/ (replicated), or g:/ (geo-distributed with 20% discount)
  • Ensure path matches where your app writes data
  • For databases: specify correct data directory
Persistent storage examplesjson
{
  "name": "postgres",
  "repotag": "postgres:15-alpine",
  "containerData": "s:/var/lib/postgresql/data",  // Single node storage
  "cpu": 1.0,
  "ram": 2000,
  "hdd": 20
}

// For geo-distributed apps (20% cost discount)
{
  "name": "minecraft",
  "containerData": "g:/data/minecraft",  // Geo-distributed with syncing
  "cpu": 2.0,
  "ram": 4000,
  "hdd": 30
}

Out of disk space

Symptoms:

  • •Write failed: no space left on device
  • •Application crashes when writing files

Solutions:

  • Increase hdd value in your spec
  • Clean up unnecessary files in your Docker image
  • Use multi-stage builds to reduce image size
  • Implement log rotation in your app
  • Monitor disk usage and scale up before hitting limits

Performance Problems

Application running slow or timing out

Symptoms:

  • •Slow response times
  • •Requests timing out
  • •High latency

Solutions:

  • Increase CPU allocation in your spec
  • Increase RAM if app is memory-intensive
  • Optimize database queries and add indexes
  • Add caching layer (Redis) to reduce database load
  • Use CDN for static assets
  • Profile your application to find bottlenecks
  • Check for memory leaks in your application

Out of memory errors

Symptoms:

  • •Container killed
  • •OOM (Out of Memory) errors

Solutions:

  • Increase ram value in your spec
  • Optimize memory usage in your application
  • Implement pagination for large datasets
  • Use streaming for large file operations
  • Check for memory leaks
Resource allocationjson
{
  // Small app
  "cpu": 0.5,
  "ram": 1000,
  "hdd": 5,

  // Medium app
  "cpu": 2.0,
  "ram": 4000,
  "hdd": 20,

  // Large app
  "cpu": 4.0,
  "ram": 8000,
  "hdd": 50
}

Still Need Help?

Flux Discord

Join the Flux community Discord for real-time help and support

Join Discord

Flux Documentation

Official Flux documentation and guides

View Docs