Skip to main content

Common Issues

This guide covers common problems you might encounter when using Dokploy and their solutions.

Installation Issues

Installation Script Fails

Problem: Installation fails because Docker is not installed.Solution:
Problem: Port 3000 or 80/443 is already in use.Solution:
Problem: Permission denied errors during installation.Solution:

Deployment Issues

Build Failures

Problem: Build process times out.Solution:
  • Increase build timeout in application settings
  • Optimize your build process (remove unnecessary dependencies)
  • Check server resources (CPU, memory)
  • Use Docker layer caching
Problem: Build fails with out of memory error.Solution:
Or upgrade your server to have more RAM.
Problem: Nixpacks cannot detect or build your application.Solution:
  • Ensure your project has the correct files (package.json, requirements.txt, etc.)
  • Try using a different build provider (Buildpacks or Dockerfile)
  • Check Nixpacks logs for specific errors
  • Add a nixpacks.toml configuration file
Problem: Cannot clone repository.Solution:
  • Verify repository URL is correct
  • Check SSH key configuration for private repos
  • Ensure branch name is correct
  • Verify network connectivity
  • Check Git provider authentication

Runtime Issues

Problem: Container starts but application doesn’t run.Solution:
  • Check application logs in Dokploy dashboard
  • Verify environment variables are set correctly
  • Ensure the start command is correct
  • Check if required ports are exposed
  • Verify database connections
Problem: Container starts then immediately exits.Solution:
Problem: Getting 502 errors when accessing application.Solution:
  • Verify application is listening on the correct port
  • Check if application is running: docker ps
  • Ensure port is correctly configured in Dokploy
  • Check Traefik logs for routing issues
  • Verify health check endpoint exists

Database Issues

Problem: Application cannot connect to database.Solution:
  • Verify database is running: Check in Dokploy dashboard
  • Ensure connection string is correct
  • Check database credentials in environment variables
  • Verify network connectivity between containers
  • Use internal Docker network hostnames
Example connection string:
Problem: Automated backups are failing.Solution:
  • Check storage destination is configured correctly
  • Verify S3/storage credentials
  • Ensure sufficient disk space
  • Check backup logs for specific errors
  • Test manual backup first
Problem: Database migrations don’t run or fail.Solution:
  • Run migrations manually first
  • Check migration scripts for errors
  • Verify database user has sufficient privileges
  • Ensure migration command is correct in deployment settings
  • Check application logs for migration errors

Docker Issues

Problem: Cannot connect to Docker daemon.Solution:
Problem: Cannot access Docker socket.Solution:
Problem: Running out of disk space.Solution:

Network & SSL Issues

Problem: Let’s Encrypt certificate fails to generate.Solution:
  • Verify domain DNS points to your server IP
  • Wait for DNS propagation (can take up to 48 hours)
  • Ensure ports 80 and 443 are open
  • Check for rate limiting from Let’s Encrypt
  • Verify email is configured correctly
Problem: Cannot access application via domain.Solution:
  • Verify DNS A record points to server IP
  • Check domain configuration in Dokploy
  • Ensure Traefik is running properly
  • Check firewall rules allow ports 80/443
  • Verify application is running
Problem: Traefik not routing requests correctly.Solution:

Performance Issues

Problem: Server experiencing high CPU usage.Solution:
  • Check which containers are using CPU: docker stats
  • Scale horizontally with multi-node setup
  • Optimize application code
  • Add CPU limits to containers
  • Upgrade server resources
Problem: Running out of memory.Solution:
Consider upgrading server RAM or optimizing applications.
Problem: Deployments take too long.Solution:
  • Use Docker layer caching
  • Optimize Dockerfile (multi-stage builds)
  • Reduce image size
  • Use faster storage (SSD)
  • Upgrade network speed
  • Pre-pull base images

API & Automation Issues

Problem: API requests return 401 Unauthorized.Solution:
  • Verify API token is correct
  • Check token hasn’t expired
  • Ensure Authorization header is properly formatted:
  • Generate a new API token if needed
Problem: Webhooks not triggering deployments.Solution:
  • Verify webhook URL is correct
  • Check webhook logs in Git provider
  • Ensure webhook secret matches (if configured)
  • Test webhook manually with curl
  • Check firewall allows incoming webhook requests

Multi-Node Issues

Problem: Cannot connect to remote node.Solution:
  • Verify SSH access to remote server
  • Check firewall rules on remote server
  • Ensure Docker is installed on remote server
  • Verify Docker Swarm is initialized
  • Check network connectivity between nodes
Problem: Docker Swarm not working properly.Solution:

Logging & Debugging

View Logs

Debug Mode

Enable verbose logging for troubleshooting:

Getting Help

If you’re still experiencing issues:

Discord Community

Get real-time help from the community

GitHub Issues

Report bugs or request features

FAQ

Check frequently asked questions

Documentation

Browse the complete documentation

Reporting Issues

When reporting an issue, include:
  1. Dokploy version: Check in dashboard settings
  2. Server details: OS, RAM, CPU
  3. Error messages: Complete error logs
  4. Steps to reproduce: What you did before the error
  5. Expected vs actual behavior: What should happen vs what happens
  6. Screenshots: If applicable
The more information you provide, the faster we can help resolve your issue!