🐳 Docker Error Guide: 'secret not found' on stack deploy and service create

Exact Error Message

$ docker stack deploy -c docker-compose.yml myapp
Creating network myapp_default
Creating service myapp_api
failed to create service myapp_api: Error response from daemon: rpc error: code = InvalidArgument desc = secret not found: db_password

The docker service create form produces the same underlying message:

$ docker service create --name api --secret db_password nginx
Error response from daemon: secret not found: db_password

What It Means

Docker Swarm secrets are cluster-level objects stored in the encrypted Raft log on the manager nodes. When you reference a secret by name in a service or stack, the swarm looks it up in that store at scheduling time. secret not found means the swarm cannot resolve the name you gave to an existing secret object. The service is never created, so nothing starts.

This is a lookup failure, not a permission or mount failure. The secret has to already exist as a swarm object before the service that consumes it is created. Compose files with external: true secrets are the most common place this bites, because Docker assumes you created the secret out of band and does not create it for you.

Common Causes

• The secret was never created with docker secret create.
• A typo or case mismatch between the secret name and the reference in the service or Compose file.
• The Compose file declares the secret as external: true, but no matching external secret exists in the swarm.
• You created the secret on a different swarm, or the node was removed and rejoined a new cluster, so the Raft store no longer has it.
• You ran the command against a standalone daemon or a worker node instead of a swarm manager.
• The secret was removed by another operator or a teardown script that ran out of order.

Diagnostic Commands

List every secret the swarm currently knows about and confirm the exact name:

docker secret ls

Inspect the specific secret to verify it exists and see when it was created:

docker secret inspect db_password

Confirm you are on a swarm manager, since secrets are only readable there:

docker node ls
docker info --format '{{.Swarm.LocalNodeState}} {{.Swarm.ControlAvailable}}'

Check how the Compose file references the secret, including whether it is external:

grep -A3 'secrets:' docker-compose.yml

Step-by-Step Resolution

1. Verify the secret is missing. Run docker secret ls and compare the printed names against the exact string in your error. Names are case-sensitive and must match character for character.

2. Create the secret if it does not exist. Pipe a value from stdin so it never lands in shell history or a file:

printf '%s' 'S3cr3tValue' | docker secret create db_password -

Or create it from a file:

docker secret create db_password ./db_password.txt

3. If your Compose file marks the secret external, make the declared name match the object you just created:

secrets:
  db_password:
    external: true

If you named the swarm object differently, point Compose at it explicitly:

secrets:
  db_password:
    external: true
    name: prod_db_password_v2

4. Re-deploy the stack. Secrets are immutable, so redeploying picks up the now-existing object:

docker stack deploy -c docker-compose.yml myapp

5. Confirm the service converged and mounted the secret:

docker service ps myapp_api
docker exec $(docker ps -q -f name=myapp_api) ls -l /run/secrets/

6. To rotate a secret, create a new versioned object, update the service to reference it, then remove the old one. You cannot update a secret in place:

printf '%s' 'newvalue' | docker secret create db_password_v2 -
docker service update --secret-rm db_password --secret-add db_password_v2 myapp_api

Prevention

• Create every external secret before the first docker stack deploy, ideally in a bootstrap script that runs against the manager.
• Keep secret names in a single source of truth so the Compose reference and the created object never drift apart. The DevOps AI prompt library has prompts that generate matching secret-create commands from a Compose file.
• Use versioned secret names (db_password_v2) and update services to rotate, rather than deleting and recreating with the same name.
• Run deploys only from a manager node in CI; fail fast if docker info reports the node is not a swarm manager.
• Store the plaintext values in an external vault and inject them at docker secret create time, never committing them to git.

Related Errors

• config not found: <name> — the identical problem for swarm configs instead of secrets.
• This node is not a swarm manager — you are trying to manage secrets from a worker or standalone daemon.
• rpc error: code = AlreadyExists desc = secret <name> already exists — you tried to recreate a secret that is already present; secrets are immutable.
• invalid mount config for type "bind" — a different mount problem, unrelated to swarm secrets.

Frequently Asked Questions

Why does the secret work in one environment but not another? Secrets live in each swarm’s Raft store and are not portable. A secret created on your staging swarm does not exist on production. Create it separately on every cluster.

Can Docker Compose create the secret for me? Only when the secret is defined with a file: source and you deploy with docker stack deploy; even then it must be created before the consuming service schedules. An external: true secret is never created by Docker and must exist beforehand.

How do I update a secret value? You cannot edit a secret in place because they are immutable. Create a new secret with a new name, update the service with --secret-rm and --secret-add, then delete the old one.

Do I need to be on a manager node? Yes. Secret create, list, and inspect only work on swarm managers, since workers never receive the decryption keys for the Raft log.

Why do I see the error even though docker secret ls shows the secret? Check for trailing whitespace, case differences, or that Compose uses a different name: override. The reference must resolve to the exact object name. For more, see the Docker guides.