docker/cli · error

- specify one with --advertise-addr

Error message

%w - specify one with --advertise-addr

What it means

Wraps a daemon error from SwarmInit when the manager could not determine an IP address to advertise. The CLI detects the phrases 'could not choose an IP address to advertise' / 'could not find the system's IP address' and appends guidance to set --advertise-addr.

Solutions

1. Provide an explicit advertise address: 'docker swarm init --advertise-addr <ip|iface>'.
2. Ensure at least one non-loopback interface is up with an IP ('ip addr').
3. In containers, run with appropriate network visibility (--net=host or a known interface).

Example fix

# before
docker swarm init

# after
docker swarm init --advertise-addr 10.0.0.5
# -or-
docker swarm init --advertise-addr eth0

// Probe interfaces and supply --advertise-addr proactively
if addr, err := pickFirstGlobalIPv4(); err == nil {
    args = append(args, "--advertise-addr", addr)
}

func hasAdvertiseAddr(flags *pflag.FlagSet) bool {
	return flags.Changed(flagAdvertiseAddr)
}

if err := runInit(ctx, cli, flags, opts); err != nil {
    if strings.Contains(err.Error(), "specify one with --advertise-addr") {
        // retry with a discovered interface address
        flags.Set(flagAdvertiseAddr, discoveredAddr)
        return runInit(ctx, cli, flags, opts)
    }
    return err
}

When it happens

Trigger: 'docker swarm init' on a host whose network interfaces are all down, loopback-only, ambiguous (multiple IPs with no clear choice), or in a restricted container without host networking. The daemon returns an advertise-selection error which the CLI re-wraps.

Common situations: Init in a container without host network mode; multi-homed hosts; air-gapped VMs with only lo; CI runners with no routable interface.

Related errors

• invalid IP address
• service is already attached to network
• network is declared as external, but could not be found…
• network is declared as external, but it is not in the right…
• failed to create network

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/d1ee38d58ea994a2. Report an issue: GitHub.

Appendix: source

Thrown at cli/command/swarm/init.go:113

			return fmt.Errorf("invalid availability %q, only active, pause and drain are supported", opts.availability)
		}
	}

	res, err := apiClient.SwarmInit(ctx, client.SwarmInitOptions{
		ListenAddr:       opts.listenAddr.String(),
		AdvertiseAddr:    opts.advertiseAddr,
		DataPathAddr:     opts.dataPathAddr,
		DataPathPort:     opts.dataPathPort,
		DefaultAddrPool:  defaultAddrPool,
		ForceNewCluster:  opts.forceNewCluster,
		Spec:             opts.swarmOptions.ToSpec(flags),
		AutoLockManagers: opts.swarmOptions.autolock,
		Availability:     availability,
		SubnetSize:       opts.DefaultAddrPoolMaskLength,
	})
	if err != nil {
		if strings.Contains(err.Error(), "could not choose an IP address to advertise") || strings.Contains(err.Error(), "could not find the system's IP address") {
			return fmt.Errorf("%w - specify one with --advertise-addr", err)
		}
		return err
	}

	_, _ = fmt.Fprintf(dockerCLI.Out(), "Swarm initialized: current node (%s) is now a manager.\n\n", res.NodeID)

	if err := printJoinCommand(ctx, dockerCLI, res.NodeID, true, false); err != nil {
		return err
	}

	_, _ = fmt.Fprintln(dockerCLI.Out(), "To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.")

	if opts.swarmOptions.autolock {
		resp, err := apiClient.SwarmGetUnlockKey(ctx)
		if err != nil {
			return fmt.Errorf("could not fetch unlock key: %w", err)
		}
		printUnlockCommand(dockerCLI.Out(), resp.Key)

View on GitHub (pinned to 4f84911bfe)