docker/compose · error · ErrForbidden

forbidden

Error message

forbidden

What it means

api.ErrForbidden is the sentinel returned when an operation is not permitted — typically authorization failure against the backend (e.g. a cloud backend rejecting an action for the current credentials). It exists so the CLI and library consumers can map permission problems consistently rather than parse strings.

Source

Thrown at pkg/api/errors.go:35

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 {
	return errors.Is(err, ErrNotFound)
}

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Re-authenticate with an account that has the required permissions (docker login).
2. Check token scopes / org policies for the operation you are attempting.
3. In Go code, detect with errors.Is(err, api.ErrForbidden) and surface a permission message rather than retrying.

func isForbidden(err error) bool { return errors.Is(err, api.ErrForbidden) }

if err := op(ctx); err != nil {
    if errors.Is(err, api.ErrForbidden) {
        // stop and prompt re-login / report permission gap; do not retry
        return fmt.Errorf("permission denied: %w", err)
    }
    return err
}

When it happens

Trigger: Calling an api operation the authenticated principal lacks rights for; a compose (cloud) backend receiving an HTTP 403 and wrapping it as ErrForbidden for the caller.

Common situations: Expired or scoped-down Docker accounts/tokens used with the cloud backend; org-level RBAC denying registry or environment access; using a read-only token for mutating operations.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• not found
• already exists
• unknown
• not implemented
• unsupported flag

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