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:
# Install Docker first
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

# Then install Dokploy
curl -sSL https://dokploy.com/install.sh | sh
Problem: Port 3000 or 80/443 is already in use.Solution:
# Check what's using the port
sudo lsof -i :3000
sudo lsof -i :80

# Stop conflicting services
sudo systemctl stop <service-name>

# Or configure Dokploy to use different ports
Problem: Permission denied errors during installation.Solution:
# Run installation with sudo
curl -sSL https://dokploy.com/install.sh | sudo sh

# Or fix Docker permissions
sudo usermod -aG docker $USER
newgrp docker

​
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:
# Increase Docker memory limit
# Edit /etc/docker/daemon.json
{
  "default-runtime": "runc",
  "default-shm-size": "2g"
}

# Restart Docker
sudo systemctl restart docker
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:
# View container logs
docker logs <container-id>

# Common issues:
# - Missing environment variables
# - Database connection errors
# - Port conflicts
# - File permission issues
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:
postgresql://user:password@postgres-container:5432/dbname
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:
# Start Docker service
sudo systemctl start docker

# Enable Docker to start on boot
sudo systemctl enable docker

# Check Docker status
sudo systemctl status docker
Problem: Cannot access Docker socket.Solution:
# Add user to docker group
sudo usermod -aG docker $USER

# Apply group changes
newgrp docker

# Or fix socket permissions
sudo chmod 666 /var/run/docker.sock
Problem: Running out of disk space.Solution:
# Remove unused containers
docker container prune -f

# Remove unused images
docker image prune -a -f

# Remove unused volumes
docker volume prune -f

# Clean up everything
docker system prune -a --volumes -f

​
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:
# Check Traefik logs
docker logs dokploy-traefik

# Restart Traefik
docker restart dokploy-traefik

# Verify Traefik configuration
docker exec dokploy-traefik cat /etc/traefik/traefik.yml

​
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:
# Check memory usage
docker stats --no-stream

# Set memory limits for containers
# In Dokploy UI: Settings > Resources > Memory Limit
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: 
    -H "Authorization: Bearer YOUR_TOKEN"
  • 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:
# Check swarm status
docker info | grep Swarm

# List swarm nodes
docker node ls

# Reinitialize swarm if needed
docker swarm leave --force
docker swarm init

​
Logging & Debugging

​
View Logs

# Application logs (in Dokploy dashboard)
# Or via Docker:
docker logs <container-name>

# Follow logs in real-time
docker logs -f <container-name>

# Last 100 lines
docker logs --tail 100 <container-name>

# Dokploy system logs
docker logs dokploy-dokploy

# Traefik logs
docker logs dokploy-traefik

# Database logs
docker logs <database-container>

​
Debug Mode

Enable verbose logging for troubleshooting: 
# Add to environment variables
DEBUG=*
LOG_LEVEL=debug

​
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!

Build docs developers (and LLMs) love

Get started for freeTalk to us