Home / Docker / Docker Swarm Join Failed: How to Connect Nodes to the Cluster

Docker

Docker Swarm Join Failed: How to Connect Nodes to the Cluster

Resolve Docker Swarm join failures with diagnosis of token issues, network connectivity, and firewall configuration with practical solutions.

Published: Nov 13, 20259 min readBy FixWikiHub Editorial Team

Abstract illustration for a troubleshooting knowledge base category.

# Docker Swarm Join Failed: How to Connect Nodes to the Cluster

You tried to join a Docker Swarm node, but it failed:

bash

Error response from daemon: rpc error: code = Unavailable desc = all SubConns are in TransientFailure

Or:

bash

Error response from daemon: invalid join token

Adding nodes to a Swarm cluster should be straightforward, but several issues can block the connection. Let me walk you through diagnosing and fixing Swarm join failures.

Introduction

This article covers troubleshooting steps and solutions for Docker Swarm Join Failed: How to Connect Nodes to the Cluster. 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 = Unavailable desc = all SubConns are in TransientFailure

bash

Error response from daemon: invalid join token

```bash # On a manager node, get the current join token docker swarm join-token worker

# Output: # To add a worker to this swarm, run the following command: # docker swarm join --token SWMTKN-1-xxx... IP:2377

# Get manager join token docker swarm join-token manager

# Rotate tokens if compromised docker swarm join-token --rotate worker ```

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 the Join Process

1.When joining a Swarm, a node needs three things:
2.A valid join token (worker or manager)
3.Network connectivity to existing managers
4.Proper firewall configuration for Swarm ports

Step 1: Verify the Join Token

Join tokens expire and can be invalid:

```bash # On a manager node, get the current join token docker swarm join-token worker

# Output: # To add a worker to this swarm, run the following command: # docker swarm join --token SWMTKN-1-xxx... IP:2377

# Get manager join token docker swarm join-token manager

# Rotate tokens if compromised docker swarm join-token --rotate worker ```

Common token issues:

bash

# Token might be expired or rotated
# Always get fresh token from manager
docker swarm join-token worker -q  # Quiet output, just the token

Step 2: Check Manager Node Availability

The manager nodes must be reachable:

```bash # On the joining node, test connectivity to manager ping MANAGER_IP

# Test the Swarm port specifically nc -zv MANAGER_IP 2377

# Or use curl curl -v MANAGER_IP:2377

# Check manager status from manager node docker node ls ```

If manager is unreachable:

```bash # Check manager's Docker daemon # On manager: docker info | grep Swarm systemctl status docker

# Check if Swarm is active docker node ls ```

Step 3: Firewall Configuration

Swarm requires specific ports to be open:

Required ports:

Port	Protocol	Purpose
2377	TCP	Swarm management
4789	UDP	VXLAN overlay network
7946	TCP/UDP	Container network discovery

Configure firewall (iptables):

```bash # Open Swarm management port iptables -A INPUT -p tcp --dport 2377 -j ACCEPT

# Open VXLAN port iptables -A INPUT -p udp --dport 4789 -j ACCEPT

# Open gossip port iptables -A INPUT -p tcp --dport 7946 -j ACCEPT iptables -A INPUT -p udp --dport 7946 -j ACCEPT

# Save rules iptables-save > /etc/iptables/rules.v4 ```

For firewalld:

bash

firewall-cmd --add-port=2377/tcp --permanent
firewall-cmd --add-port=4789/udp --permanent
firewall-cmd --add-port=7946/tcp --permanent
firewall-cmd --add-port=7946/udp --permanent
firewall-cmd --reload

For ufw:

bash

ufw allow 2377/tcp
ufw allow 4789/udp
ufw allow 7946/tcp
ufw allow 7946/udp
ufw reload

Step 4: Network Interface Issues

Swarm needs to bind to the correct network interface:

```bash # Check available interfaces ip addr show

# Join with specific advertise address docker swarm join --advertise-addr eth0 --token TOKEN MANAGER_IP:2377

# Or with specific IP docker swarm join --advertise-addr 192.168.1.100 --token TOKEN MANAGER_IP:2377 ```

Multiple interfaces:

If the node has multiple network interfaces, specify which one to use:

bash

docker swarm join \
  --advertise-addr 192.168.1.100:2377 \
  --listen-addr 0.0.0.0:2377 \
  --token TOKEN \
  MANAGER_IP:2377

Step 5: Check Docker Daemon Configuration

The Docker daemon must be properly configured:

```bash # Check Docker daemon status systemctl status docker

# View Docker info docker info

# Check daemon logs journalctl -u docker.service -n 50 ```

Common daemon issues:

```bash # Docker might not be running systemctl start docker

# Restart Docker if it's stuck systemctl restart docker

# Check daemon.json for conflicts cat /etc/docker/daemon.json ```

Step 6: Remove Existing Swarm State

If the node was previously in a Swarm:

```bash # Leave existing Swarm docker swarm leave --force

# Clean up Swarm state rm -rf /var/lib/docker/swarm

# Restart Docker systemctl restart docker

# Now join fresh docker swarm join --token TOKEN MANAGER_IP:2377 ```

Step 7: TLS and Certificate Issues

Swarm uses mutual TLS. Certificate problems cause join failures:

```bash # Error: x509: certificate signed by unknown authority # This indicates a mismatch in Swarm CA

# Solution: Leave and rejoin docker swarm leave --force # Get fresh token from manager docker swarm join --token NEW_TOKEN MANAGER_IP:2377 ```

Certificate rotation (on manager):

```bash # Rotate Swarm CA certificate docker swarm ca --rotate

# Wait for rotation to complete docker swarm ca --rotate --detach=false ```

Step 8: Check Manager Quorum

If too many managers are down, the cluster loses quorum:

```bash # On a working manager docker node ls

# Check manager availability docker info | grep "Managers"

# If quorum is lost, recovery is complex # Backup Raft data carefully ```

Manager recovery:

```bash # If quorum lost, force recovery on remaining manager docker swarm init --force-new-cluster

# Re-add other managers docker swarm join-token manager ```

Step 9: Debug Join Process

Use verbose output to diagnose:

```bash # Check Docker daemon logs during join journalctl -u docker.service -f

# Try join and watch output docker swarm join --token TOKEN MANAGER_IP:2377 2>&1 | tee join.log

# Test port connectivity explicitly telnet MANAGER_IP 2377 ```

Step 10: Verify Successful Join

After joining, confirm the node is in the cluster:

```bash # On the new node docker info | grep Swarm # Should show: Swarm: active

# Check node ID docker info | grep NodeID

# On manager, verify node is listed docker node ls

# Check node status docker node inspect SELF ```

Common Error Patterns and Fixes

Error	Cause	Fix
`invalid join token`	Token expired or wrong	Get fresh token from manager
`all SubConns are in TransientFailure`	Network unreachable	Check firewall and connectivity
`x509 certificate error`	CA mismatch	Leave and rejoin with fresh token
`already part of a swarm`	Existing Swarm membership	Leave current Swarm first
`manager unreachable`	Network or firewall	Open ports 2377, 4789, 7946

Complete Join Workflow

```bash # On manager: get token TOKEN=$(docker swarm join-token worker -q) echo "Join token: $TOKEN"

# On joining node: test connectivity nc -zv MANAGER_IP 2377

# Join the Swarm docker swarm join --token $TOKEN MANAGER_IP:2377

# Verify docker info | grep Swarm ```

Prevention

1.Document join tokens securely but rotate regularly
2.Configure firewalls before joining nodes
3.Use static IPs for manager advertise addresses
4.Monitor manager health to maintain quorum
5.Keep backup managers for redundancy

Verification

Task	Command
Get worker token	`docker swarm join-token worker`
Get manager token	`docker swarm join-token manager`
Rotate token	`docker swarm join-token --rotate worker`
Join Swarm	`docker swarm join --token TOKEN IP:2377`
Leave Swarm	`docker swarm leave --force`
List nodes	`docker node ls`
Check ports	`nc -zv IP 2377`

Swarm join failures are usually caused by invalid tokens, firewall blocks, or network interface issues. Verify the token is current, ensure ports are open, and specify the correct advertise address.

[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 Join Failed: How to Connect Nodes to the Cluster Docker Swarm Join Failed: How to Connect Nodes to the Cluster Docker Docker Swarm Join Failed: How to Connect Nodes to the Cluster troubleshooting Docker Swarm Join Failed: How to Connect Nodes to the Cluster fix Resolve Docker Swarm join failures with diagnosis of token issues, network connectivity, and firewall configuration with practical solutions Docker Resolve Docker Swarm join failures with diagnosis of token issues, network connectivity, and firewall configuration with practical solutions

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 Join Failed: How to Connect Nodes to the Cluster

Introduction

Symptoms

Common Causes

Step-by-Step Fix

Understanding the Join Process

Step 1: Verify the Join Token

Step 2: Check Manager Node Availability

Step 3: Firewall Configuration

Step 4: Network Interface Issues

Step 5: Check Docker Daemon Configuration

Step 6: Remove Existing Swarm State

Step 7: TLS and Certificate Issues

Step 8: Check Manager Quorum

Step 9: Debug Join Process

Step 10: Verify Successful Join

Common Error Patterns and Fixes

Complete Join Workflow

Prevention

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 Join Failed: How to Connect Nodes to the Cluster

Introduction

Symptoms

Common Causes

Step-by-Step Fix

Understanding the Join Process

Step 1: Verify the Join Token

Step 2: Check Manager Node Availability

Step 3: Firewall Configuration

Step 4: Network Interface Issues

Step 5: Check Docker Daemon Configuration

Step 6: Remove Existing Swarm State

Step 7: TLS and Certificate Issues

Step 8: Check Manager Quorum

Step 9: Debug Join Process

Step 10: Verify Successful Join

Common Error Patterns and Fixes

Complete Join Workflow

Prevention

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