docker/cli · error

failed to create service

Error message

failed to create service %s: %w

What it means

Raised by deployServices when creating a new service (not present in the stack namespace) and ServiceCreate fails. The wrapped %w carries the daemon error. This is the first-deploy path or the path for services newly added to the stack.

Solutions

1. Read the wrapped error for the daemon's rejection reason.
2. Ensure every service has a valid image and all referenced networks/secrets/configs are present.
3. Check `docker node ls` for available nodes matching any placement constraints.
4. Confirm the image exists and registry auth is correct (use --with-registry-auth).
5. Retry if the manager was temporarily unavailable.

Example fix

// before: service missing an image (caught earlier) or invalid spec
services:
  web:
    build: .          # no image: for swarm deploy you must also set image
// after: provide an image for swarm deploy
services:
  web:
    image: myregistry/web:latest
    build: .

// Validate every service before deploy: image present, refs resolve, constraints satisfiable
for _, svc := range services {
    if _, err := reference.ParseAnyReference(svc.Image); err != nil {
        return fmt.Errorf("service %s invalid image: %w", svc.Name, err)
    }
    if err := referencedSecretsAndConfigsExist(svc); err != nil { return err }
    if !constraintsSatisfiable(svc.Placement, availableNodes) {
        return fmt.Errorf("service %s placement unsatisfiable", svc.Name)
    }
}

When it happens

Trigger: First deploy of a stack, or adding a new service to an existing stack; ServiceCreate at deploy_composefile.go:288 returns an error (invalid spec, missing image, scheduling failure, name collision).

Common situations: Invalid or missing image; name collision with a service outside the stack; referencing non-existent networks/secrets/configs; resource constraints no node satisfies; manager unreachable or not a swarm node.

Related errors

• failed to update service
• %s: %w
• this node is not a swarm manager. Use "docker swarm init"…
• failed to create secret
• failed to create config

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

Appendix: source

Thrown at cli/command/stack/deploy_composefile.go:294

			for _, warning := range response.Warnings {
				_, _ = fmt.Fprintln(dockerCLI.Err(), warning)
			}

			serviceIDs = append(serviceIDs, svc.ID)
		} else {
			_, _ = fmt.Fprintln(out, "Creating service", name)

			// query registry if flag disabling it was not set
			queryRegistry := resolveImage == resolveImageAlways || resolveImage == resolveImageChanged

			response, err := apiClient.ServiceCreate(ctx, client.ServiceCreateOptions{
				Spec:                serviceSpec,
				EncodedRegistryAuth: encodedAuth,
				QueryRegistry:       queryRegistry,
			})
			if err != nil {
				return nil, fmt.Errorf("failed to create service %s: %w", name, err)
			}

			serviceIDs = append(serviceIDs, response.ID)
		}
	}

	return serviceIDs, nil
}

func waitOnServices(ctx context.Context, dockerCli command.Cli, serviceIDs []string, quiet bool) error {
	var errs []error
	for _, serviceID := range serviceIDs {
		if err := service.WaitOnService(ctx, dockerCli, serviceID, quiet); err != nil {
			errs = append(errs, fmt.Errorf("%s: %w", serviceID, err))
		}
	}
	return errors.Join(errs...)
}

View on GitHub (pinned to 4f84911bfe)