multiple services found with provided prefix: {service}

Error message

multiple services found with provided prefix: {service}

What it means

In `createFilter()` (ps.go:122-126), when a service argument doesn't match by full ID or full name, the code attempts an ID-prefix match (line 123-131). If the prefix matches more than one service ID, the error is returned at line 126. This is the ambiguous-prefix scenario: the provided ID prefix is too short to uniquely identify a single service.

Source

Thrown at cli/command/service/ps.go:126

		for _, s := range serviceByID.Items {
			if s.ID == service {
				filter.Add("service", s.ID)
				serviceCount++
				continue loop
			}
		}
		for _, s := range serviceByName.Items {
			if s.Spec.Annotations.Name == service {
				filter.Add("service", s.ID)
				serviceCount++
				continue loop
			}
		}
		found := false
		for _, s := range serviceByID.Items {
			if strings.HasPrefix(s.ID, service) {
				if found {
					return filter, nil, errors.New("multiple services found with provided prefix: " + service)
				}
				filter.Add("service", s.ID)
				serviceCount++
				found = true
			}
		}
		if !found {
			notfound = append(notfound, "no such service: "+service)
		}
	}
	if serviceCount == 0 {
		return filter, nil, errors.New(strings.Join(notfound, "\n"))
	}
	return filter, notfound, err
}

func updateNodeFilter(ctx context.Context, apiClient client.APIClient, filter client.Filters) error {
	if nodeFilters, ok := filter["node"]; ok {

View on GitHub (pinned to 4f84911bfe)

Solutions

Provide a longer service ID prefix to disambiguate — use enough characters to be unique
Use the full service name instead of an ID prefix: `docker service ps <service-name>`
List all services to find the full ID: `docker service ls`

Example fix

# before (ambiguous prefix)
docker service ps ab
# error: multiple services found with provided prefix: ab

# after (use full name)
docker service ps my-web-service

# after (use longer unique prefix)
docker service ps abc123def456

Defensive patterns

Strategy: validation

Validate before calling

// Before calling runPS, resolve ambiguous prefixes
func resolveServicePrefix(ctx context.Context, c client.APIClient, prefix string) (string, error) {
    services, err := c.ServiceList(ctx, client.ServiceListOptions{
        Filters: make(client.Filters).Add("id", prefix),
    })
    if err != nil {
        return "", err
    }
    if len(services.Items) > 1 {
        return "", fmt.Errorf("multiple services found with prefix: %s", prefix)
    }
    if len(services.Items) == 0 {
        return "", fmt.Errorf("no such service: %s", prefix)
    }
    return services.Items[0].ID, nil
}

Prevention

Use full service IDs or unambiguous names instead of short prefixes
In large swarms, short ID prefixes collide frequently — use at least 12 characters
Resolve service references to full IDs before batch operations

When it happens

Trigger: Running `docker service ps ab` when two services have IDs starting with `ab` (e.g., `abc123...` and `abd456...`). The prefix `ab` matches both, triggering the ambiguity error. This check occurs before any tasks are listed — it is returned from `createFilter` directly.

Common situations: An operator copies a short prefix of a service ID. In a large swarm with many services, short prefixes frequently collide. Also common in scripts that truncate IDs for display.

Related errors

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