# Docker Stack Deploy Failed: How to Troubleshoot Swarm Deployments

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

bash
failed to deploy stack: services failed to create/update

Or:

bash
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.

Introduction

This article covers troubleshooting steps and solutions for Docker Stack Deploy Failed: How to Troubleshoot Swarm Deployments. The error typically occurs in production environments and can cause service disruptions if not addressed promptly.

Symptoms

Common error messages include:

bash
failed to deploy stack: services failed to create/update
bash
failed to create service myapp_web: network not found
failed to create service myapp_db: image not found

```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 ```

Common Causes

  • Configuration misconfiguration
  • Missing or incorrect credentials
  • Network connectivity issues
  • Version compatibility problems
  • Resource exhaustion or limits
  • Permission or access denied

Step-by-Step Fix

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:

bash
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:

yaml
# docker-compose.yml
networks:
  external_net:
    external: true
    name: my_external_network  # Must exist
bash
# 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:

yaml
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:

bash
# 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:

yaml
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

ErrorCauseFix
build key not supportedbuild directive in SwarmUse pre-built images
network not foundExternal network missingCreate network first
no suitable nodePlacement constraint failedAdd node labels or relax constraints
image not foundImage doesn't existBuild/pull image
secret not foundSecret doesn't existCreate secret
resources insufficientNode lacks capacityRelax limits or add nodes

Stack vs Compose Differences

FeatureDocker ComposeDocker Stack
buildSupportedNot supported
depends_onSupportedLimited (no condition)
volumesHost-specificNode-specific
networksDefault bridgeOverlay by default
scaleManualVia deploy.replicas
restartrestart: alwaysdeploy.restart_policy

Prevention

  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

Verification

TaskCommand
Deploy stackdocker stack deploy -c compose.yml NAME
List stacksdocker stack ls
List servicesdocker stack services NAME
List tasksdocker stack ps NAME
Remove stackdocker stack rm NAME
Validate composedocker-compose config

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.

  • [Fix docker build cache invalidated unnecessary layers Issue in Docker-Errors](docker-build-cache-invalidated-unnecessary-layers)
  • [Fix Docker Build Cache Invalidation Optimization Issue in Docker](docker-build-cache-invalidation-optimization)
  • [Fix docker build context slow large files Issue in Docker-Errors](docker-build-context-slow-large-files)
  • [Fix docker build multi stage copy from not found Issue in Docker-Errors](docker-build-multi-stage-copy-from-not-found)
  • [Fix docker buildkit export local tar layer missing Issue in Docker-Errors](docker-buildkit-export-local-tar-layer-missing)

<script type="application/ld+json"> { "@context": "https://schema.org", "@type": "TechArticle", "headline": "Docker Stack Deploy Failed: How to Troubleshoot Swarm Deployments", "description": "Troubleshoot Docker Swarm stack deployment failures. Fix compose file issues, resolve network problems, and debug service constraints.", "url": "https://www.fixwikihub.com/fix-docker-stack-deploy-failed", "publisher": { "@type": "Organization", "name": "FixWikiHub", "url": "https://www.fixwikihub.com" }, "author": { "@type": "Person", "name": "FixWikiHub Editorial Team" }, "datePublished": "2025-11-13T05:15:46.165Z", "dateModified": "2025-11-13T05:15:46.165Z" } </script>