GitHub Actions "A runner with the same name already exists"

GitHub requires unique runner names within a scope. Registering a new runner with a name still held by a stale or live registration fails until you replace or rename it.

What this error means

config.sh fails during self-hosted runner registration with a duplicate-name error.

Error: A runner with the same name already exists.
Use --replace to replace the existing runner, or choose a different name.

Common causes

Stale registration not removed

A previous runner with that name was not deregistered (host died without cleanup).

Reusing a name across hosts

Two machines try to register with the same name.

How to fix it

Replace or rename the registration

1. Re-run config.sh with --replace to take over the existing name, or
2. Choose a unique name (e.g. include the hostname).
3. Remove the stale runner from Settings > Actions > Runners if it lingers.

./config.sh --url https://github.com/ORG/REPO --token TOKEN --name "runner-${HOSTNAME}" --replace

How to prevent it

• Use unique, host-derived runner names.
• Deregister runners on host teardown.

Related guides