feat(api): a typed error for a service with no running container

Exec, port, export, commit and attach fail with "service X is not running"
when they find no container to act on. A program driving Compose as a library
could only recognise that failure by matching the message.

Return a ServiceNotRunningError, which matches the new ErrNotRunning and
carries the service and the replica index. The message is unchanged.

Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>
This commit is contained in:
Nicolas De Loof 2026-10-28 15:56:05 +01:00 • committed by Guillaume Lours
parent bd07e0b4c0
commit f5efe67ea3
4 changed files with 83 additions and 5 deletions

View file

@ -18,6 +18,7 @@ package api
import (
"errors"
"fmt"
)
const (
@ -48,6 +49,9 @@ var (
// ErrIncompatibleOptions is returned when a set of options that cannot be
// honored together is requested. See IncompatibleOptionsError.
ErrIncompatibleOptions = errors.New("incompatible options")
// ErrNotRunning is returned when an operation targets a service, or a
// replica of it, that has no running container. See ServiceNotRunningError.
ErrNotRunning = errors.New("not running")
// ErrInvalidOption is returned when an option is set to a value it does
// not accept. See InvalidOptionError.
ErrInvalidOption = errors.New("invalid option")
@ -98,6 +102,35 @@ func IsErrIncompatibleOptions(err error) bool {
return errors.Is(err, ErrIncompatibleOptions)
}
// ServiceNotRunningError reports that an operation which acts on one container
// of a service (exec, port, export, commit, attach…) found no matching
// container, that is no running one for most of them. It
// matches ErrNotRunning with errors.Is, and callers needing the details can
// retrieve it with errors.As.
type ServiceNotRunningError struct {
// Service is the name of the service that was targeted.
Service string
// Index is the replica that was asked for, 0 when none in particular was.
Index int
}
func (e *ServiceNotRunningError) Error() string {
if e.Index > 0 {
return fmt.Sprintf("service %q is not running container #%d", e.Service, e.Index)
}
return fmt.Sprintf("service %q is not running", e.Service)
}
// Unwrap makes errors.Is(err, ErrNotRunning) hold.
func (e *ServiceNotRunningError) Unwrap() error {
return ErrNotRunning
}
// IsErrNotRunning returns true if the unwrapped error is ErrNotRunning
func IsErrNotRunning(err error) bool {
return errors.Is(err, ErrNotRunning)
}
// IsErrInvalidOption returns true if the unwrapped error is ErrInvalidOption
func IsErrInvalidOption(err error) bool {
return errors.Is(err, ErrInvalidOption)

View file

@ -51,3 +51,17 @@ func TestIsUnknown(t *testing.T) {
assert.Assert(t, !IsUnknownError(errors.New("another error")))
}
func TestServiceNotRunningError(t *testing.T) {
err := fmt.Errorf("exec: %w", &ServiceNotRunningError{Service: "web"})
assert.Assert(t, IsErrNotRunning(err))
assert.Assert(t, !IsNotFoundError(err))
assert.ErrorContains(t, err, `service "web" is not running`)
var notRunning *ServiceNotRunningError
assert.Assert(t, errors.As(err, &notRunning))
assert.Equal(t, notRunning.Service, "web")
assert.Error(t, &ServiceNotRunningError{Service: "web", Index: 3}, `service "web" is not running container #3`)
assert.Assert(t, !IsErrNotRunning(errors.New("another error")))
}

View file

@ -18,7 +18,6 @@ package compose
import (
"context"
"fmt"
"slices"
"sort"
"strconv"
@ -118,10 +117,7 @@ func (s *composeService) getSpecifiedContainer(ctx context.Context, projectName
}
containers := res.Items
if len(containers) < 1 {
if containerIndex > 0 {
return container.Summary{}, fmt.Errorf("service %q is not running container #%d", serviceName, containerIndex)
}
return container.Summary{}, fmt.Errorf("service %q is not running", serviceName)
return container.Summary{}, &api.ServiceNotRunningError{Service: serviceName, Index: containerIndex}
}
// Sort by container number first, then put one-off containers at the end

View file

@ -17,10 +17,13 @@
package compose
import (
"errors"
"testing"
"github.com/compose-spec/compose-go/v2/types"
"github.com/moby/moby/api/types/container"
"github.com/moby/moby/client"
"go.uber.org/mock/gomock"
"gotest.tools/v3/assert"
"github.com/docker/compose/v5/pkg/api"
@ -69,3 +72,35 @@ func TestIsOrphaned(t *testing.T) {
})
}
}
// TestGetSpecifiedContainerNotRunning pins the error of an operation that
// targets a service with no running container: callers must be able to tell it
// from any other failure without matching the message, which stays the same.
func TestGetSpecifiedContainerNotRunning(t *testing.T) {
tests := []struct {
name string
index int
message string
}{
{name: "any replica", index: 0, message: `service "web" is not running`},
{name: "given replica", index: 2, message: `service "web" is not running container #2`},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
mockCtrl := gomock.NewController(t)
apiClient, cli := prepareMocks(mockCtrl)
tested, err := NewComposeService(cli)
assert.NilError(t, err)
apiClient.EXPECT().ContainerList(gomock.Any(), gomock.Any()).Return(client.ContainerListResult{}, nil)
_, err = tested.(*composeService).getSpecifiedContainer(t.Context(), testProject, oneOffExclude, false, "web", tt.index)
assert.Error(t, err, tt.message)
assert.Assert(t, errors.Is(err, api.ErrNotRunning), "got %v", err)
var notRunning *api.ServiceNotRunningError
assert.Assert(t, errors.As(err, &notRunning))
assert.Equal(t, notRunning.Service, "web")
assert.Equal(t, notRunning.Index, tt.index)
})
}
}