none of the selected services is configured for watch, see h

Error message

none of the selected services is configured for watch, see https://docs.docker.com/compose/how-tos/file-watch/

What it means

The watch command tries to build watch rules for the selected services and only succeeds if at least one has a develop section with watch entries (or legacy x-develop). If no eligible service remains after filtering, it returns this error pointing at the file-watch documentation.

Source

Thrown at pkg/compose/watch.go:78

func NewWatcher(project *types.Project, options api.UpOptions, w WatchFunc, consumer api.LogConsumer) (*Watcher, error) {
	for i := range project.Services {
		service := project.Services[i]

		if service.Develop != nil && service.Develop.Watch != nil {
			build := options.Create.Build
			return &Watcher{
				project: project,
				options: api.WatchOptions{
					LogTo: consumer,
					Build: build,
				},
				watchFn: w,
				errCh:   make(chan error),
			}, nil
		}
	}
	// none of the services is eligible to watch
	return nil, fmt.Errorf("none of the selected services is configured for watch, see https://docs.docker.com/compose/how-tos/file-watch/")
}

// ensure state changes are atomic
var mx gsync.Mutex

func (w *Watcher) Start(ctx context.Context) error {
	mx.Lock()
	defer mx.Unlock()
	ctx, cancelFunc := context.WithCancel(ctx)
	w.stopFn = cancelFunc
	wait, err := w.watchFn(ctx, w.project, w.options)
	if err != nil {
		go func() {
			w.errCh <- err
		}()
		return err
	}
	go func() {

View on GitHub (pinned to ddc4b044b6)

Solutions

Add a develop: section with watch: rules to at least one service you intend to watch.
If using a selector, include the service that actually has develop.watch configured.
Verify the compose file being used is the intended one (docker compose config shows develop blocks).
Follow the linked documentation (https://docs.docker.com/compose/how-tos/file-watch/) for the supported develop schema.

Example fix

# before
services:
  web:
    build: .
    # no develop section

# after
services:
  web:
    build: .
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src

Defensive patterns

Strategy: validation

Validate before calling

func anyServiceWatchable(project *types.Project) bool {
	for _, svc := range project.Services {
		if svc.Develop != nil && len(svc.Develop.Watch) > 0 {
			return true
		}
	}
	return false
}

Try / catch

if _, err := composeService.Watch(ctx, projectName, opts); err != nil {
    if strings.Contains(err.Error(), "none of the selected services is configured for watch") {
        // add a develop.watch block or stop calling watch for this stack
    }
    return err
}

Prevention

Only invoke watch on stacks authored with develop.watch sections.
Validate compose files contain develop.watch before starting watch in dev scripts.
Keep watch config in the same file as the service it applies to.

When it happens

Trigger: Running docker compose watch with no service in scope having a develop.watch configuration — either no develop blocks at all, or the services named in the command all lacking watch rules.

Common situations: Running watch on a stack authored only for deployment (no develop sections); invoking watch with a service selector that excludes the one watched service; compose file authored for an older compose version using x-develop unsupported in this path.

Related errors

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