Home / Docker / Docker Swarm Secret Not Found: How to Create and Manage Secrets

Docker

Docker Swarm Secret Not Found: How to Create and Manage Secrets

Resolve Docker Swarm secret not found errors with secret creation, service configuration fixes, and proper secret management strategies.

Published: Nov 13, 20258 min readBy FixWikiHub Editorial Team

Abstract illustration for a troubleshooting knowledge base category.

# Docker Swarm Secret Not Found: How to Create and Manage Secrets

Your Swarm service fails to deploy because a referenced secret doesn't exist:

bash

Error response from daemon: rpc error: code = 2 desc = secret db_password not found

Or:

bash

service myapp: failed to update service: secret not found: api_key

Docker Swarm secrets provide secure storage for sensitive data, but services fail if referenced secrets aren't created first. Let me show you how to fix this.

Introduction

This article covers troubleshooting steps and solutions for Docker Swarm Secret Not Found: How to Create and Manage Secrets. The error typically occurs in production environments and can cause service disruptions if not addressed promptly.

Symptoms

Common error messages include:

bash

Error response from daemon: rpc error: code = 2 desc = secret db_password not found

bash

service myapp: failed to update service: secret not found: api_key

```bash # List all secrets docker secret ls

# Output: # ID NAME DRIVER CREATED # abc123def456 db_password 2 hours ago

# Inspect a specific secret (limited info) docker secret inspect db_password ```

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 Docker Swarm Secrets

Secrets in Swarm are: - Created on manager nodes - Encrypted and stored in the Raft log - Delivered to containers via files in /run/secrets/ - Never visible in docker inspect output

Step 1: List Existing Secrets

Check what secrets are already in the Swarm:

```bash # List all secrets docker secret ls

# Output: # ID NAME DRIVER CREATED # abc123def456 db_password 2 hours ago

# Inspect a specific secret (limited info) docker secret inspect db_password ```

Step 2: Create Missing Secrets

If the secret doesn't exist, create it:

```bash # Create from file docker secret create db_password ./password.txt

# Create from stdin echo "my_secret_password" | docker secret create db_password -

# Create from stdin with echo suppression docker secret create db_password - <<< "my_secret_password"

# Verify creation docker secret ls | grep db_password ```

Important: Secrets are immutable. Once created, you cannot update them. To change a secret's value, create a new secret with a different name.

Step 3: Fix Service Configuration

Update your service to reference the correct secret:

```bash # Check current service configuration docker service inspect myapp --format '{{json .Spec.TaskTemplate.ContainerSpec.Secrets}}'

# Update service with correct secret reference docker service update --secret-add source=db_password,target=db_password myapp ```

In docker-compose.yml:

```yaml version: '3.8' secrets: db_password: external: true # Must exist in Swarm

services: app: image: myapp:latest secrets: - db_password ```

If using external secrets, create them before deploying:

bash

docker secret create db_password -
docker stack deploy -c docker-compose.yml myapp

Step 4: Create Secrets in Compose Files

Alternatively, let Compose create secrets from files:

```yaml version: '3.8' secrets: db_password: file: ./secrets/db_password.txt # Create from file

services: app: image: myapp:latest secrets: - source: db_password target: db_password.txt uid: '1000' gid: '1000' mode: 0400 ```

Note: file secrets work with docker-compose for non-Swarm deployment, but Swarm requires external or uses file when creating the stack.

Step 5: Access Secrets in Containers

Inside containers, secrets appear as files:

```bash # Check where secrets are mounted docker exec <container> ls -la /run/secrets/

# Read secret content docker exec <container> cat /run/secrets/db_password

# In your application code password = open('/run/secrets/db_password').read().strip() ```

Step 6: Handle Secret Updates

Secrets cannot be modified. To update a secret value:

```bash # Create a new secret version docker secret create db_password_v2 - <<< "new_password"

# Update service to use new secret docker service update \ --secret-rm db_password \ --secret-add source=db_password_v2,target=db_password \ myapp

# Remove old secret after migration docker secret rm db_password ```

Or use a naming convention:

bash

# Rotate secrets systematically
docker secret create myapp_db_password_20260403 - <<< "password"
docker service update --secret-add myapp_db_password_20260403 myapp

Step 7: Debug Secret Issues

If services fail due to secrets:

```bash # Check service logs docker service logs myapp

# Inspect service task docker service ps myapp

# Check task error message docker service ps myapp --no-trunc

# Look for: "secret not found" or similar ```

Verify secret is in Swarm:

```bash # List secrets docker secret ls

# Check secret ID matches service reference docker service inspect myapp --format '{{json .Spec.TaskTemplate.ContainerSpec.Secrets}}' ```

Step 8: Remove Unused Secrets

Clean up secrets no longer needed:

```bash # List secrets with no references docker secret ls

# Check which services use a secret docker service ls --format "{{.Name}}" | while read s; do docker service inspect $s --format '{{range .Spec.TaskTemplate.ContainerSpec.Secrets}}{{.SecretName}}{{"\n"}}{{end}}' done | grep -c db_password

# Remove secret docker secret rm db_password ```

Note: You cannot remove a secret that's actively used by running services.

Step 9: Secret Target Configuration

Configure how secrets appear in containers:

```bash # Basic secret reference docker service create \ --name myapp \ --secret db_password \ myimage:latest

# With custom target path docker service create \ --name myapp \ --secret source=db_password,target=/etc/app/password \ myimage:latest

# With specific permissions docker service create \ --name myapp \ --secret source=db_password,target=password,uid=1000,gid=1000,mode=0400 \ myimage:latest ```

In docker-compose.yml:

```yaml secrets: db_password: external: true

services: app: secrets: - source: db_password target: /etc/app/password uid: '1000' gid: '1000' mode: 0400 ```

Step 10: Grant Secret Access to Services

Services must explicitly request secrets:

```yaml # WRONG: Secret referenced but not granted access secrets: api_key: external: true

services: app: # Missing secrets section

# CORRECT: Explicitly grant secret access secrets: api_key: external: true

services: app: secrets: - api_key ```

Common Error Patterns and Fixes

Error	Cause	Fix
`secret not found`	Secret doesn't exist in Swarm	Create secret first
`invalid secret reference`	Wrong secret ID or name	Update service with correct name
`secret in use`	Cannot remove active secret	Remove service first
`secret file not found`	Compose file path wrong	Verify file exists

Complete Secret Workflow

```bash # 1. Create secret echo "my_password" | docker secret create db_password -

# 2. Verify docker secret ls

# 3. Deploy service with secret docker service create --name myapp --secret db_password myimage

# 4. Verify secret is accessible docker exec $(docker ps -q -f name=myapp) cat /run/secrets/db_password

# 5. Update secret (create new version) echo "new_password" | docker secret create db_password_v2 -

# 6. Update service docker service update --secret-rm db_password --secret-add db_password_v2 myapp ```

Best Practices for Secret Management

1.Use meaningful names with version suffixes
2.Rotate secrets regularly by creating new versions
3.Limit secret permissions (mode 0400, specific uid/gid)
4.Never log secret contents in application code
5.Create secrets before deploying stacks
6.Document secret creation for team members

Verification

Task	Command
List secrets	`docker secret ls`
Create secret	`docker secret create NAME -`
Create from file	`docker secret create NAME file.txt`
Inspect secret	`docker secret inspect NAME`
Remove secret	`docker secret rm NAME`
Add to service	`docker service update --secret-add NAME service`
Remove from service	`docker service update --secret-rm NAME service`
Check secret in container	`docker exec CONTAINER cat /run/secrets/NAME`

Secret errors are resolved by creating the secret before referencing it in services. Remember that secrets are immutable—you need to create new versions for updates.

[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)

Was this guide helpful?

Related search paths

People also search for

If the symptom is close but not identical, these search paths usually surface the right neighboring fixes faster than scrolling the full archive.

Docker Swarm Secret Not Found: How to Create and Manage Secrets Docker Swarm Secret Not Found: How to Create and Manage Secrets Docker Docker Swarm Secret Not Found: How to Create and Manage Secrets troubleshooting Docker Swarm Secret Not Found: How to Create and Manage Secrets fix Resolve Docker Swarm secret not found errors with secret creation, service configuration fixes, and proper secret management strategies Docker Resolve Docker Swarm secret not found errors with secret creation, service configuration fixes, and proper secret management strategies

Explore Related Topics

Browse Guides from Other Categories

Discover troubleshooting guides from related categories to expand your knowledge.

FAQ

Docker Troubleshooting FAQs

Common questions about troubleshooting and preventing similar issues

How do I know if this docker-errors troubleshooting guide applies to my situation?

This guide is designed for docker-errors issues. If you're experiencing similar symptoms described in the article, follow the step-by-step instructions. Start with the most common causes and work through the diagnostic process.

Is it safe to follow these docker-errors troubleshooting steps?

Yes, all steps are designed to be safe and non-destructive. We recommend creating backups before making significant changes and testing each step before proceeding to the next.

How long does it typically take to resolve this type of docker-errors issue?

Most docker-errors issues can be resolved within 30 minutes to 2 hours, depending on the complexity and root cause. Follow the troubleshooting flow to identify and fix the problem efficiently.

How can I prevent this docker-errors issue from happening again?

Regular maintenance, monitoring, and following best practices for docker-errors configuration can help prevent recurrence. Consider implementing automated checks and alerts for early detection.

Written by

FixWikiHub Editorial Team

Our editorial team consists of experienced DevOps engineers, systems administrators, and cloud architects with hands-on experience in production environments across AWS, Azure, GCP, and on-premises infrastructure.

Every guide undergoes technical review for accuracy and is updated when software versions, commands, or best practices change.

Last updated: Nov 13, 2025

About our team

Important Notice

Disclaimer & Safety Guidelines

The troubleshooting steps in this guide are provided for educational and informational purposes. Before applying any changes to production systems:

Test in a staging environment first — Always verify commands and configurations in a non-production environment before deploying to live systems.
Create backups — Ensure you have current backups of databases, configurations, and critical files before making changes.
Understand the impact — Review how each step may affect your specific environment, dependencies, and users.
Consult official documentation — This guide supplements, but does not replace, official vendor documentation and best practices.

FixWikiHub is not responsible for any damages arising from the use of this content. See our Terms of Use for more information.

Resources

Official Documentation & Further Reading

For authoritative information, consult the official documentation for the technologies discussed in this guide. Our troubleshooting content supplements, but does not replace, vendor documentation.

AWS Documentation — Official Amazon Web Services guides and API references
Kubernetes Documentation — Official Kubernetes documentation
Nginx Documentation — Official Nginx web server documentation
Apache Documentation — Official Apache HTTP Server documentation
Docker Documentation — Official Docker container documentation

Docker Swarm Secret Not Found: How to Create and Manage Secrets

Introduction

Symptoms

Common Causes

Step-by-Step Fix

Understanding Docker Swarm Secrets

Step 1: List Existing Secrets

Step 2: Create Missing Secrets

Step 3: Fix Service Configuration

Step 4: Create Secrets in Compose Files

Step 5: Access Secrets in Containers

Step 6: Handle Secret Updates

Step 7: Debug Secret Issues

Step 8: Remove Unused Secrets

Step 9: Secret Target Configuration

Step 10: Grant Secret Access to Services

Common Error Patterns and Fixes

Complete Secret Workflow

Best Practices for Secret Management

Verification

People also search for

Browse Guides from Other Categories

WordPress

SSL

DNS

Docker Troubleshooting FAQs

FixWikiHub Editorial Team

Disclaimer & Safety Guidelines

Official Documentation & Further Reading

Docker Swarm Secret Not Found: How to Create and Manage Secrets

Introduction

Symptoms

Common Causes

Step-by-Step Fix

Understanding Docker Swarm Secrets

Step 1: List Existing Secrets

Step 2: Create Missing Secrets

Step 3: Fix Service Configuration

Step 4: Create Secrets in Compose Files

Step 5: Access Secrets in Containers

Step 6: Handle Secret Updates

Step 7: Debug Secret Issues

Step 8: Remove Unused Secrets

Step 9: Secret Target Configuration

Step 10: Grant Secret Access to Services

Common Error Patterns and Fixes

Complete Secret Workflow

Best Practices for Secret Management

Verification

Related Articles

People also search for

Share this guide

More Docker Troubleshooting Guides

Browse Guides from Other Categories

Docker Troubleshooting FAQs

FixWikiHub Editorial Team

Disclaimer & Safety Guidelines

Official Documentation & Further Reading