docker/compose · error · ErrAlreadyExists

already exists

Error message

already exists

What it means

api.ErrAlreadyExists is the canonical sentinel for attempting to create an object that already exists (for example creating a resource with the same name twice). Like the other api sentinels it is meant to be detected with errors.Is or api.IsAlreadyExistsError, letting callers distinguish conflicts from other failures.

Source

Thrown at pkg/api/errors.go:33

*/

package api

import (
	"errors"
)

const (
	// ExitCodeLoginRequired exit code when command cannot execute because it requires cloud login
	// This will be used by VSCode to detect when creating context if the user needs to login first
	ExitCodeLoginRequired = 5
)

var (
	// ErrNotFound is returned when an object is not found
	ErrNotFound = errors.New("not found")
	// ErrAlreadyExists is returned when an object already exists
	ErrAlreadyExists = errors.New("already exists")
	// ErrForbidden is returned when an operation is not permitted
	ErrForbidden = errors.New("forbidden")
	// ErrUnknown is returned when the error type is unmapped
	ErrUnknown = errors.New("unknown")
	// ErrNotImplemented is returned when a backend doesn't implement an action
	ErrNotImplemented = errors.New("not implemented")
	// ErrUnsupportedFlag is returned when a backend doesn't support a flag
	ErrUnsupportedFlag = errors.New("unsupported flag")
	// ErrCanceled is returned when the command was canceled by user
	ErrCanceled = errors.New("canceled")
	// ErrParsingFailed is returned when a string cannot be parsed
	ErrParsingFailed = errors.New("parsing failed")
	// ErrNoResources is returned when operation didn't selected any resource
	ErrNoResources = errors.New("no resources")
)

// IsNotFoundError returns true if the unwrapped error is ErrNotFound
func IsNotFoundError(err error) bool {

View on GitHub (pinned to ddc4b044b6)

Solutions

  1. Check for the object's existence before creating it, or treat IsAlreadyExistsError as success when idempotency is desired.
  2. Remove/rename the existing object if a fresh create is required.
  3. Serialize concurrent creation steps (lock or ordering) so only one creator runs.
Defensive patterns

Strategy: try-catch

Validate before calling

docker compose ls --format json | jq -e --arg p "$PROJECT" 'map(.Name) | index($p)' >/dev/null || echo "project $PROJECT already absent"

Type guard

func isAlreadyExists(err error) bool { return api.IsAlreadyExistsError(err) }

Try / catch

err := createResource(...)
if err != nil {
    if api.IsAlreadyExistsError(err) {
        err = nil // idempotent success
    }
}

Prevention

When it happens

Trigger: Programmatic calls into pkg/api that create a named resource which is already present; backends wrap engine conflict responses into this sentinel so the CLI layer can react (e.g. skip creation or surface a clear message).

Common situations: Re-running a provisioning flow without cleanup; concurrent processes creating the same compose resource; scripts that assume idempotent create semantics.

Related errors

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