docker/compose · error · ErrNotFound

not found

Error message

not found

What it means

api.ErrNotFound is the compose api package's sentinel for a missing object (project, service, container). It is a package-level errors.New value designed to be compared with errors.Is / api.IsNotFoundError after unwrapping, so backends (compose, cloud) can map engine-specific not-found conditions onto one canonical error.

Source

Thrown at pkg/api/errors.go:31

   See the License for the specific language governing permissions and
   limitations under the License.
*/

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")
)

View on GitHub (pinned to ddc4b044b6)

Solutions

  1. Verify the project/service name exists (docker compose ls, docker compose config --services) and fix the reference.
  2. In Go code, branch on api.IsNotFoundError(err) to handle absence gracefully instead of string matching.
  3. If the project was expected, check you are in the right project directory / -p flag value.
Defensive patterns

Strategy: try-catch

Validate before calling

names=$(docker compose config --services 2>/dev/null)
case " $names " in *" $SERVICE "*) ;; *) echo "unknown service: $SERVICE" >&2; exit 1 ;; esac

Type guard

func isNotFound(err error) bool { return api.IsNotFoundError(err) }

Try / catch

if err := backend.Start(ctx, projectName, api.StartOptions{}); err != nil {
    if api.IsNotFoundError(err) {
        // object absent: create it or skip
    }
    return err
}

Prevention

When it happens

Trigger: Calling api methods that return ErrNotFound directly, or wrapping it with %w when a lookup by name fails; API consumers hit it when the referenced project or service does not exist (e.g. Start on an unknown service name).

Common situations: Scripts referencing a service that was renamed or removed from the compose file; race where the project was torn down between commands; programmatic use of pkg/api where a name mismatch occurs.

Related errors

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