Docker Stack Deploy Failed: How to Troubleshoot Swarm Deployments

# Docker Stack Deploy Failed: How to Troubleshoot Swarm Deployments

You tried to deploy a stack to Docker Swarm, but it failed:

failed to deploy stack: services failed to create/update

Or:

failed to create service myapp_web: network not found
failed to create service myapp_db: image not found

Stack deployments combine Docker Compose files with Swarm orchestration. Let me show you how to debug and fix these failures.

Understanding Stack Deployments

Stacks use docker-compose.yml files but run on Swarm: - Services become Swarm services (scalable, load-balanced) - Networks become Swarm overlay networks - Volumes work differently (local volumes per node) - build directives don't work (must use pre-built images)

Step 1: Validate Compose File for Swarm

Swarm requires specific compose features:

```bash # Check compose file validity docker-compose config

# Test stack deploy dry-run (not available, use config) docker-compose config | grep -E "build|volumes|depends_on"

# Swarm-specific validation docker stack config -c docker-compose.yml --compose-format # If available ```

Key Swarm constraints:

```yaml # WRONG: build directive doesn't work in Swarm services: app: build: .

# CORRECT: use pre-built image services: app: image: myapp:latest

# WRONG: depends_on doesn't control startup order in Swarm services: app: depends_on: - db

# CORRECT: use health checks and deploy constraints services: app: depends_on: db: condition: service_healthy ```

Step 2: Check Swarm Status

Ensure Swarm is initialized:

```bash # Check Swarm status docker info | grep Swarm

# Should show: Swarm: active

# If inactive, initialize docker swarm init

# List existing stacks docker stack ls

# Check nodes are ready docker node ls ```

Step 3: Diagnose Specific Service Failures

When deploy fails, identify which service:

```bash # Attempt deploy docker stack deploy -c docker-compose.yml myapp

# Check services created docker stack services myapp

# Check tasks for failed services docker stack ps myapp --no-trunc

# View error details docker service ps myapp_web --no-trunc ```

Common failure messages:

no suitable node (unsatisfied constraint)
network not found
image not found
secret not found
config not found

Step 4: Fix Image Issues

Stacks require pre-built images:

```bash # Check if images exist docker images | grep myapp

# Build images before stack deploy docker-compose build docker-compose push # If using registry

# Or pull from registry docker pull myapp:latest

# Ensure all services have images grep "image:" docker-compose.yml ```

Private registry images:

```bash # Login to registry docker login registry.example.com

# Ensure images are accessible docker pull registry.example.com/myapp:latest ```

Step 5: Fix Network Issues

Networks may not exist or have conflicts:

```bash # Check existing networks docker network ls | grep myapp

# For external networks, create first docker network create --driver overlay myapp_network

# Or let stack create it docker stack deploy -c docker-compose.yml myapp docker network ls | grep myapp_default ```

External network configuration:

# docker-compose.yml
networks:
  external_net:
    external: true
    name: my_external_network  # Must exist

# Create external network before deploy
docker network create -d overlay --attachable my_external_network
docker stack deploy -c docker-compose.yml myapp

Step 6: Fix Placement Constraints

Services may fail if no node matches constraints:

services:
  app:
    deploy:
      placement:
        constraints:
          - node.role == manager
          - node.labels.zone == east

Check node labels:

```bash # List nodes with labels docker node ls --format "{{.Hostname}} {{.Status}}"

# Check node labels docker node inspect node-1 --format '{{json .Spec.Labels}}'

# Add missing labels docker node update --label-add zone=east node-1 ```

Or remove constraints:

# Update service without constraints
docker service update --constraint-rm node.role myapp_app

Step 7: Fix Secrets and Configs

Swarm services need secrets and configs created first:

```yaml secrets: db_password: external: true

configs: app_config: external: true ```

Create before deploying:

```bash # Create secrets echo "password" | docker secret create db_password -

# Create configs docker config create app_config ./config.json

# Now deploy docker stack deploy -c docker-compose.yml myapp ```

Step 8: Handle Resource Limits

Services may fail due to resource constraints:

services:
  app:
    deploy:
      resources:
        limits:
          memory: 512M

Check node resources:

```bash # Check node capacity docker node inspect node-1 --format '{{.Description.Resources}}'

# Check available resources docker node ls --format "{{.Hostname}}" docker info | grep -A 5 "Memory|CPU"

# Relax resource limits docker service update --limit-memory 256M myapp_app ```

Step 9: Debug Service Logs

Examine logs for failure reasons:

```bash # View service logs docker service logs myapp_web

# View task logs (if task failed) docker service ps myapp_web

# Check specific task docker inspect TASK_ID

# Daemon logs journalctl -u docker.service | grep -i "service|task" ```

Step 10: Remove and Redeploy

Sometimes a clean slate helps:

```bash # Remove the stack docker stack rm myapp

# Wait for complete removal docker stack ls

# Clean up networks docker network prune

# Redeploy docker stack deploy -c docker-compose.yml myapp ```

Step 11: Compose Version Compatibility

Use compatible compose versions:

```yaml # Recommended version for Swarm version: '3.8'

# Some features require specific versions: # version: '3.2' minimum for deploy section # version: '3.3' for configs # version: '3.5' for secrets in services # version: '3.8' recommended for full features ```

Full Debug Workflow

```bash # 1. Validate compose file docker-compose config

# 2. Check Swarm status docker info | grep Swarm docker node ls

# 3. Pull/build images docker-compose pull docker images | grep myapp

# 4. Create external resources docker secret create db_password - docker config create app_config ./config.json docker network create -d overlay myapp_net

# 5. Deploy stack docker stack deploy -c docker-compose.yml myapp

# 6. Check deployment status docker stack services myapp docker stack ps myapp --no-trunc

# 7. Check failed services docker service logs myapp_web docker service ps myapp_web --no-trunc

# 8. Debug if needed docker service inspect myapp_web ```

Common Stack Deploy Errors

Stack vs Compose Differences

Best Practices

1. 1.Pre-build images and push to registry
2. 2.Use health checks for service readiness
3. 3.Test compose locally before Swarm deploy
4. 4.Create secrets/configs before deployment
5. 5.Pin image versions for reproducibility
6. 6.Use meaningful stack names for management

Quick Reference

Stack deploy failures are usually caused by missing images, networks, secrets, or node constraints. Validate the compose file, ensure external resources exist, and check that nodes meet placement requirements.