How to fix Error response from daemon: invalid join token in Docker

First, get a fresh join token from an existing swarm manager. SSH into any manager node and run:

For worker nodes:

docker swarm join-token worker

For manager nodes:

docker swarm join-token manager

This outputs the complete join command including the token. The output looks like:

To add a worker to this swarm, run the following command:

    docker swarm join --token SWMTKN-1-5k3... 192.168.1.100:2377

Copy the entire command exactly as shown, including the IP address and port.

Ensure you're using the right token for your intended role:

- Worker token: Allows the node to join as a worker (runs containers but doesn't participate in swarm management)
- Manager token: Allows the node to join as a manager (participates in Raft consensus and can manage the swarm)

If you accidentally used the wrong token type, get the correct one:

# On a manager node - get worker token only (no command, just token)
docker swarm join-token -q worker

# On a manager node - get manager token only (no command, just token)
docker swarm join-token -q manager

The -q flag outputs just the token string without the full join command, which is useful for automation.

Join tokens are long strings that are easy to truncate or corrupt when copying:

Valid token format:

SWMTKN-1-<25 characters>-<25 characters>

Check your token:
1. Ensure it starts with SWMTKN-1-
2. Count the sections - there should be exactly 3 parts separated by hyphens after "SWMTKN-1-"
3. Check for trailing spaces or newline characters
4. Ensure no characters were cut off

Test by echoing the token:

# Store in variable and verify
TOKEN="SWMTKN-1-your-token-here"
echo "Token: [$TOKEN]"
echo "Length: ${#TOKEN}"

A valid token is typically 96+ characters long.

If you suspect the token has been compromised or is in an unknown state, rotate it on the manager:

# Rotate worker token
docker swarm join-token --rotate worker

# Rotate manager token
docker swarm join-token --rotate manager

This invalidates all previous tokens for that role and generates a new one. The command also outputs the new join command.

Important: After rotating, update all scripts and documentation that reference the old token - it will no longer work.

If the node was previously part of this or another swarm, it may retain stale state. Leave the current swarm first:

# On the node trying to join
docker swarm leave

# Force leave if necessary (e.g., if it was a manager)
docker swarm leave --force

Then attempt to join again with a fresh token from the manager:

docker swarm join --token SWMTKN-1-... <manager-ip>:2377

Note: If you see "This node is already part of a swarm", you must leave first.

When using Ansible, Terraform, or shell scripts, token handling issues are common:

Ansible example (correct approach):

- name: Get worker join token
  command: docker swarm join-token -q worker
  register: worker_token
  delegate_to: "{{ swarm_manager }}"

- name: Join swarm as worker
  command: >
    docker swarm join
    --token {{ worker_token.stdout }}
    {{ swarm_manager }}:2377

Shell script (correct approach):

# Get token with -q flag for clean output
TOKEN=$(ssh manager-node "docker swarm join-token -q worker")

# Verify token is not empty
if [ -z "$TOKEN" ]; then
  echo "Failed to get join token"
  exit 1
fi

# Join using the token
docker swarm join --token "$TOKEN" manager-node:2377

Common mistakes:
- Using msg or other wrapper keys from Ansible output instead of stdout
- Not quoting the token variable ($TOKEN vs "$TOKEN")
- Including newlines in the token string

The token validation happens on the manager node. Ensure network connectivity:

# Test connectivity to manager on swarm port
nc -zv <manager-ip> 2377
# or
telnet <manager-ip> 2377

# Check if firewall allows port 2377
sudo ufw status | grep 2377
sudo firewall-cmd --list-ports | grep 2377

Required ports for Docker Swarm:
- TCP 2377: Cluster management communications
- TCP/UDP 7946: Communication among nodes
- UDP 4789: Overlay network traffic

If the manager is unreachable, the token cannot be validated and the join will fail.

Docker Swarm uses TLS certificates that expire. If certificates are expired or invalid, token validation may fail:

# On a manager node, check certificate status
docker info | grep -A 5 "Swarm"

If certificates have expired, you may need to force a new cluster:

# On the primary manager (CAUTION: only if cluster is broken)
docker swarm init --force-new-cluster

This recreates the cluster from the current manager's state, generating new certificates and tokens. All other nodes will need to rejoin.

Note: Only use --force-new-cluster as a last resort when the swarm is in a broken state.