dagger/dagger · error

incompatible engine version %s

Error message

incompatible engine version %s

What it means

After the engine starts, Connect compares the engine's reported buildkit version (c.bkVersion) against engine.MinimumEngineVersion using CheckVersionCompatibility. If the running engine is older than the minimum the client requires, Connect refuses to proceed with this message embedding the engine's normalized version. This guards against protocol incompatibilities between a new CLI and an old persisted engine.

Source

Thrown at engine/client/client.go:308

		}
		return c, nil
	}

	// Check if any of the upstream cache importers/exporters are enabled.
	// Note that this is not the cache service support in engine/cache/, that
	// is a different feature which is configured in the engine daemon.
	c.upstreamCacheImportOptions, c.upstreamCacheExportOptions, err = allCacheConfigsFromEnv()
	if err != nil {
		return nil, fmt.Errorf("cache config from env: %w", err)
	}

	c.stableClientID = GetHostStableID(slog)

	if err := c.startEngine(connectCtx, params); err != nil {
		return nil, fmt.Errorf("start engine: %w", err)
	}
	if !engine.CheckVersionCompatibility(engine.NormalizeVersion(c.bkVersion), engine.MinimumEngineVersion) {
		return nil, fmt.Errorf("incompatible engine version %s", engine.NormalizeVersion(c.bkVersion))
	}

	defer func() {
		if rerr != nil {
			c.bkClient.Close()
		}
	}()

	if err := c.startSession(connectCtx); err != nil {
		return nil, fmt.Errorf("start session: %w", err)
	}

	defer func() {
		if rerr != nil {
			c.sessionSrv.Stop()
		}
	}()

View on GitHub (pinned to 82ba2681db)

Solutions

1. Upgrade the engine: dagger engine update (or stop the old one: dagger engine stop --all, then rerun).
2. Downgrade the dagger CLI to match the running engine version if the engine can't be upgraded.
3. In CI, remove the pinned/stale engine image so a matching engine is provisioned.
4. Check versions with dagger version (CLI) and dagger query inside the session, or docker ps for the engine container's image tag.

Example fix

// before (shell)
# CLI v0.15.x talking to engine from v0.9.x
// after
dagger engine stop --all && dagger engine update && dagger version

// shell preflight
out, _ := exec.Command("docker", "ps", "--format", "{{.Image}}").CombinedOutput()
if !strings.Contains(string(out), "dagger/engine") || strings.Contains(string(out), "v0.9") {
    // stale/old engine detected; refresh before connecting
}

if _, err := dagger.Connect(ctx); err != nil && strings.Contains(err.Error(), "incompatible engine version") {
    exec.Command("dagger", "engine", "stop", "--all").Run()
    exec.Command("dagger", "engine", "update").Run()
    // then reconnect
}

When it happens

Trigger: dagger.Connect() against a long-lived engine container/daemon that predates the current CLI's minimum version — typically after upgrading the dagger CLI without upgrading the engine.

Common situations: CLI upgraded (brew/npm/ci image bump) while an old engine pod/container still runs in Docker; pinned engine image versions in CI older than MinimumEngineVersion; stale cached engine in ~/.cache/dagger.

Related errors

• merge module types into schema: %w
• failed to get services: %w
• failed to get tools: %w
• start engine: %w
• start session: %w

AI-assisted analysis of dagger/dagger@82ba2681db (2026-09-05). Data as JSON: /api/errors/6f7697b539833524. Report an issue: GitHub.