Method composeBuild

pkg/ddevapp/ddevapp.go:1439–1486

composeBuild executes docker-compose build with retry logic for BuildKit snapshot race conditions. This is an experimental workaround for moby/buildkit#6521 (Docker 29+ with containerd image store). The race condition causes intermittent failures with "parent snapshot ... does not exist: not found"

(args ...string)

// args are optional extra arguments to pass to the build command (e.g., service name, "--no-cache")
// Returns the stdout output on success, or an error if all retries are exhausted.
func (app *DdevApp) composeBuild(args ...string) (string, error) {
	progress := "plain"

	action := []string{"--progress=" + progress, "build"}
	if app.NoCache {
		action = append(action, "--no-cache")
	}
	action = append(action, args...)

	var lastErr error
	var out, stderr string

	for attempt := 1; attempt <= composeBuildMaxRetries; attempt++ {
		util.Debug("Executing docker-compose -f %s %s (attempt %d/%d)", app.DockerComposeFullRenderedYAMLPath(), strings.Join(action, " "), attempt, composeBuildMaxRetries)

		out, stderr, lastErr = dockerutil.ComposeCmd(&dockerutil.ComposeCmdOpts{
			ComposeFiles: []string{app.DockerComposeFullRenderedYAMLPath()},
			Action:       action,
			Progress:     true,
			Timeout:      time.Hour * 1,
		})

		if lastErr == nil {
			// Success
			if globalconfig.DdevVerbose {
				util.Debug("docker-compose build output:\n%s\n\n", out)
			}
			return out, nil
		}

		// Check if this is the known BuildKit snapshot race condition
		errorText := fmt.Sprintf("%v %s", lastErr, stderr)
		isSnapshotRace := strings.Contains(errorText, "parent snapshot") && strings.Contains(errorText, "does not exist")

		if !isSnapshotRace {
			// Not a snapshot race error, fail immediately without retry
			return out, fmt.Errorf("docker-compose build failed: %v, output='%s', stderr='%s'", lastErr, out, stderr)
		}

		// This is a snapshot race error - retry if we have attempts remaining
		if attempt < composeBuildMaxRetries {
			util.Warning("BuildKit snapshot race condition detected (moby/buildkit#6521). Retrying build (attempt %d/%d)...", attempt+1, composeBuildMaxRetries)
		}
	}

	// All retries exhausted
	return out, fmt.Errorf("docker-compose build failed after %d attempts: %v, output='%s', stderr='%s'", composeBuildMaxRetries, lastErr, out, stderr)
}

// Start initiates docker-compose up
func (app *DdevApp) Start() error {