Troubleshooting

This guide covers common issues you might encounter when using FTL and their solutions.

Build Issues

Registry Authentication Failures

Problem: Unable to push images to registry

Error: authentication required

Solution:

• Ensure you're using username/password authentication (token-based auth is not supported)
• Verify your registry credentials are correct
• Try logging in manually with docker login

Image Build Failures

Problem: Direct SSH transfer fails

Error: failed to transfer image layers

Solution:

• Check SSH connectivity
• Verify SSH key permissions (should be 600)
• Ensure sufficient disk space on both local and server machines

Deployment Issues

Health Check Failures

Problem: Service fails to start due to failed health checks

Error: health check failed after 3 retries

Solution:

• Verify the health check path is correct in your ftl.yaml
• Ensure your application is properly handling health check requests
• Check the service logs for application-specific errors
• Adjust health check timing parameters if needed

SSL/TLS Certificate Issues

Problem: Unable to obtain SSL certificate

Error: failed to obtain SSL certificate

Solution:

• Verify DNS records are properly configured
• Ensure the domain points to the server IP
• Check that port 80 is accessible (required for ACME challenges)
• Verify the email address in your project configuration

Networking Issues

SSH Connection Problems

Problem: Unable to connect to server

Error: ssh: connect to host example.com port 22: Connection refused

Solution:

• Verify SSH configuration
• Verify hostname/IP and port
• Check SSH key permissions

Reverse Proxy Issues

Problem: Services not accessible through domain

Error: 502 Bad Gateway

Solution:

• Verify service is running (ftl logs <service>)
• Check service port configuration
• Ensure routes are properly configured in ftl.yaml
• Verify Nginx configuration was properly generated

Volume Issues

Permission Problems

Problem: Container can't write to volume

Error: permission denied

Solution:

• Check volume ownership and permissions
• Verify volume path in configuration
• Ensure volume is properly mounted

Missing Data

Problem: Data not persisting between deployments

Error: volume not found

Solution:

• Verify volume is defined in volumes section
• Check volume mount configuration
• Ensure volumes aren't being pruned accidentally

Environment Variables

Missing Required Variables

Problem: Deployment fails due to missing variable

Error: Required environment variable 'POSTGRES_PASSWORD' is not set

Solution:

• Set required environment variables before running FTL commands
• Use environment file: source .env && ftl deploy
• Verify variable names match your configuration

Default Value Issues

Problem: Unexpected default values being used

Warning: using default value for POSTGRES_USER

Solution:

• Check environment variable syntax in ftl.yaml
• Verify variable export in your shell
• Review default values in configuration

Common Commands for Troubleshooting

# Check service logs
ftl logs <service>

# Verify connectivity
ftl setup

# Rebuild and redeploy service
ftl build && ftl deploy

Getting Help

If you encounter an issue not covered here:

1. Check the service logs using ftl logs
2. Verify your configuration against the Configuration File Reference
3. Ensure all environment variables are properly set
4. Review the CLI Commands Reference for correct usage