docker/compose · info

watch is not yet configured. Learn more

Error message

watch is not yet configured. Learn more: %s

What it means

Not a failure of compose itself: pressing 'w' in the navigation menu when the project has no watch configuration (lk.Watch == nil) deliberately raises this error, colors a docs link (https://docs.docker.com/compose/file-watch/), and displays it via keyboardError("Watch", ...). It always coexists with an attempt to open the DD watch docs page when Docker Desktop is active. After the error, ToggleWatch(ctx, options) is still called.

Solutions

1. Add a develop.watch section to compose.yaml matching services and their sync rules (see the linked docs), then re-run and press 'w'.
2. Verify the file you edited is actually part of the merged model: docker compose config | grep -A5 develop.
3. If watch is intentionally unused, ignore the message — it is informational and compose keeps running.
4. Use `docker compose watch` directly for a clearer error when the config is still missing.

Example fix

# before: compose.yaml
services:
  web:
    build: .

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

// before enabling/pressing 'w', confirm watch config is merged
cfg, err := cli.ToProject(ctx, opts)
if err == nil && cfg.Develop != nil && len(cfg.Develop.Watch) > 0 {
    // watch is configured; 'w' will toggle it
}

When it happens

Trigger: docker compose up (attached, with menu) and pressing 'w' when the loaded project model has no develop.watch section — e.g. a plain compose.yaml without a develop: block, or running from a directory where the override carrying watch config was not merged.

Common situations: Expecting `docker compose watch` behavior from the interactive menu without having written a develop.watch config; running `up` on a project whose watch config lives in a compose.override.yaml that was not loaded; muscle-memory 'w' on projects that never opted into watch.

Related errors

• watch rules MUST define a path
• can't watch service with action without a build context
• can't watch with action
• cannot publish compose file with local includes
• cannot take exclusive lock for project

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

Appendix: source

Thrown at cmd/formatter/shortcut.go:330

func (lk *LogKeyboard) HandleKeyEvents(ctx context.Context, event keyboard.KeyEvent, project *types.Project, options api.UpOptions) {
	switch kRune := event.Rune; kRune {
	case 'd':
		lk.clearNavigationMenu()
		lk.Detach()
	case 'v':
		lk.openDockerDesktop(ctx, project)
	case 'w':
		if lk.Watch == nil {
			// we try to open watch docs if DD is installed
			if lk.IsDockerDesktopActive {
				lk.openDDWatchDocs(ctx, project)
			}
			// either way we mark menu/watch as an error
			go func() {
				_ = tracing.EventWrapFuncForErrGroup(ctx, "menu/watch", tracing.SpanOptions{},
					func(ctx context.Context) error {
						err := fmt.Errorf("watch is not yet configured. Learn more: %s", ansiColor(CYAN, "https://docs.docker.com/compose/file-watch/"))
						lk.keyboardError("Watch", err)
						return err
					})()
			}()
		}
		lk.ToggleWatch(ctx, options)
	case 'o':
		lk.openDDComposeUI(ctx, project)
	case 'l':
		lk.openDDLogsView(ctx, project)
	}
	switch key := event.Key; key {
	case keyboard.KeyCtrlC:
		_ = keyboard.Close()
		lk.clearNavigationMenu()
		showCursor()

		lk.logLevel = NONE

View on GitHub (pinned to ddc4b044b6)