docker/compose · error

multiple networks with name %q were found. Use network ID as

Error message

multiple networks with name %q were found. Use network ID as `name` to avoid ambiguity

What it means

NetworkList by name returned more than one network, so the external network reference is ambiguous — Docker name filters are substring-based, and multiple networks (e.g. 'db' and 'db2', or duplicates across projects) can match. Compose refuses to guess and asks for the network ID.

Source

Thrown at pkg/compose/create.go:1495

	switch len(networks) {
	case 1:
		return networks[0].ID, nil
	case 0:
		enabled, err := s.isSwarmEnabled(ctx)
		if err != nil {
			return "", err
		}
		if enabled {
			// Swarm nodes do not register overlay networks that were
			// created on a different node unless they're in use.
			// So we can't preemptively check network exists, but
			// networkAttach will later fail anyway if network actually doesn't exist
			return "swarm", nil
		}
		return "", fmt.Errorf("network %s declared as external, but could not be found", n.Name)
	default:
		return "", fmt.Errorf("multiple networks with name %q were found. Use network ID as `name` to avoid ambiguity", n.Name)
	}
}

func (s *composeService) createVolume(ctx context.Context, volume types.VolumeConfig) error {
	eventName := fmt.Sprintf("Volume %s", volume.Name)
	s.events.On(creatingEvent(eventName))
	hash, err := VolumeHash(volume)
	if err != nil {
		return err
	}
	volume.CustomLabels = volume.CustomLabels.Add(api.ConfigHashLabel, hash)
	_, err = s.apiClient().VolumeCreate(ctx, client.VolumeCreateOptions{
		Labels:     mergeLabels(volume.Labels, volume.CustomLabels),
		Name:       volume.Name,
		Driver:     volume.Driver,
		DriverOpts: volume.DriverOpts,
	})
	if err != nil {

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Set the external network's 'name:' to the full network ID from docker network ls --no-trunc
2. Alternatively delete the duplicate networks so exactly one remains
3. Use a longer, unique network name

Example fix

# before
networks:
  default:
    name: db
    external: true
# after
networks:
  default:
    name: 6c5f2d1e9a3b  # network ID from `docker network ls`
    external: true

res, _ := cli.NetworkList(ctx, client.NetworkListOptions{Filters: client.Filters{"name": {n.Name}}})
var exact []string
for _, net := range res.Items { if net.Name == n.Name { exact = append(exact, net.ID) } }
if len(exact) != 1 { return fmt.Errorf("need exactly 1 network named %s, got %d; use ID", n.Name, len(exact)) }

When it happens

Trigger: networks: {name: X, external: true} where two or more networks have X as a name-prefix match during resolveExternalNetwork (switch case len(networks) > 1).

Common situations: Short network name that is a prefix of other names ('web' vs 'web_default'); duplicate networks created by repeated runs or manual creation; shared host with many projects.

Related errors

• network %s declared as external, but could not be found
• unsupported protocol for address: %s
• unsupported network: %s
• named pipes are only available on Windows
• creating fetcher for %s: %w

AI-assisted analysis of docker/compose@ddc4b044b6 (2026-08-15). Data as JSON: /api/errors/ab03c7554fc8a2d8. Report an issue: GitHub.