dagger/dagger · critical

buildkit client: %w

Error message

buildkit client: %w

What it means

This error wraps a failure from buildkit's client.New() call, which sets up the gRPC buildkit client connection to the remote endpoint (the Dagger engine session). The library throws it when the buildkit client cannot even be constructed — typically because the remote URL is malformed or the connection options are invalid. It indicates the client never got far enough to talk to the engine.

Source

Thrown at engine/client/buildkit.go:40

)

func newBuildkitClient(ctx context.Context, remote *url.URL, connector drivers.Connector) (_ *bkclient.Client, _ *bkclient.Info, rerr error) {
	backoffConfig := backoff.DefaultConfig
	backoffConfig.MaxDelay = 30 * time.Second
	opts := []bkclient.ClientOpt{
		bkclient.WithTracerProvider(otel.GetTracerProvider()), // TODO verify?
		bkclient.WithContextDialer(func(ctx context.Context, _ string) (net.Conn, error) {
			return connector.Connect(ctx)
		}),
		bkclient.WithGRPCDialOption(grpc.WithConnectParams(grpc.ConnectParams{
			Backoff:           backoffConfig,
			MinConnectTimeout: 10 * time.Second,
		})),
	}

	c, err := bkclient.New(ctx, remote.String(), opts...)
	if err != nil {
		return nil, nil, fmt.Errorf("buildkit client: %w", err)
	}

	ctx, cancel := context.WithTimeout(ctx, 10*time.Minute)
	defer cancel()
	if err := c.Wait(ctx); err != nil {
		return nil, nil, err
	}

	info, err := c.Info(ctx)
	if err != nil {
		return nil, nil, err
	}

	if info.BuildkitVersion.Package != engine.Package {
		return nil, nil, fmt.Errorf("remote is not a valid dagger server (expected %q, got %q)", engine.Package, info.BuildkitVersion.Package)
	}

	return c, info, nil

View on GitHub (pinned to 82ba2681db)

Solutions

1. Re-run `dagger session` / restart the engine so a fresh, valid session endpoint is generated
2. Verify the remote URL string (print remote.String() before bkclient.New) — check scheme and host are valid for buildkit (e.g. unix:// or tcp://)
3. Check that the connector's Connect function works in your environment (permissions on the socket, firewall)
4. Update dagger CLI and SDK to matching versions
5. Collect `DAGGER_LOG_LEVEL=debug` output to see the underlying wrapped err

Example fix

// before
remote, _ := url.Parse("127.0.0.1:1234") // missing scheme
// after
remote, _ := url.Parse("tcp://127.0.0.1:1234")

u, err := url.Parse(remoteStr)
if err != nil || u.Scheme == "" {
    return fmt.Errorf("invalid engine remote %q", remoteStr)
}

c, err := dagger.Connect(ctx)
if err != nil {
    if strings.Contains(err.Error(), "buildkit client:") {
        // engine session unreachable/invalid; restart engine and retry
        exec.Command("dagger", "engine", "restart").Run()
        c, err = dagger.Connect(ctx)
    }
    if err != nil { return err }
}

When it happens

Trigger: Calling newBuildkitClient (via startEngine) with a remote *url.URL whose String() form is not accepted by buildkit's client.New (e.g. unsupported scheme, empty address), or the custom context dialer/connector immediately fails in a way surfaced by client construction.

Common situations: A stale or corrupt dagger session address in ~/.docker or the session socket path; running inside an environment where the engine socket/endpoint URL is wrong (e.g. custom DAGGER_SESSION_PORT, container networking misconfig); mixing dagger CLI versions where the remote scheme changed.

Related errors

• remote is not a valid dagger server (expected %q, got %q)
• new client: %w
• failed to get main client caller: %w
• failed to create diff copy client: %w
• failed to get requester session attachables: %w

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