{"record":{"id":"a0ee5386bd35ea4a","repo":"dagger/dagger","slug":"buildkit-client-w","errorCode":null,"errorMessage":"buildkit client: %w","messagePattern":"buildkit client: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"engine/client/buildkit.go","lineNumber":40,"sourceCode":")\n\nfunc newBuildkitClient(ctx context.Context, remote *url.URL, connector drivers.Connector) (_ *bkclient.Client, _ *bkclient.Info, rerr error) {\n\tbackoffConfig := backoff.DefaultConfig\n\tbackoffConfig.MaxDelay = 30 * time.Second\n\topts := []bkclient.ClientOpt{\n\t\tbkclient.WithTracerProvider(otel.GetTracerProvider()), // TODO verify?\n\t\tbkclient.WithContextDialer(func(ctx context.Context, _ string) (net.Conn, error) {\n\t\t\treturn connector.Connect(ctx)\n\t\t}),\n\t\tbkclient.WithGRPCDialOption(grpc.WithConnectParams(grpc.ConnectParams{\n\t\t\tBackoff:           backoffConfig,\n\t\t\tMinConnectTimeout: 10 * time.Second,\n\t\t})),\n\t}\n\n\tc, err := bkclient.New(ctx, remote.String(), opts...)\n\tif err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"buildkit client: %w\", err)\n\t}\n\n\tctx, cancel := context.WithTimeout(ctx, 10*time.Minute)\n\tdefer cancel()\n\tif err := c.Wait(ctx); err != nil {\n\t\treturn nil, nil, err\n\t}\n\n\tinfo, err := c.Info(ctx)\n\tif err != nil {\n\t\treturn nil, nil, err\n\t}\n\n\tif info.BuildkitVersion.Package != engine.Package {\n\t\treturn nil, nil, fmt.Errorf(\"remote is not a valid dagger server (expected %q, got %q)\", engine.Package, info.BuildkitVersion.Package)\n\t}\n\n\treturn c, info, nil","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/dagger/dagger/blob/82ba2681dbe30d3547a1dc50ea495900ab5b6047/engine/client/buildkit.go#L22-L58","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Re-run `dagger session` / restart the engine so a fresh, valid session endpoint is generated","Verify the remote URL string (print remote.String() before bkclient.New) — check scheme and host are valid for buildkit (e.g. unix:// or tcp://)","Check that the connector's Connect function works in your environment (permissions on the socket, firewall)","Update dagger CLI and SDK to matching versions","Collect `DAGGER_LOG_LEVEL=debug` output to see the underlying wrapped err"],"exampleFix":"// before\nremote, _ := url.Parse(\"127.0.0.1:1234\") // missing scheme\n// after\nremote, _ := url.Parse(\"tcp://127.0.0.1:1234\")","handlingStrategy":"try-catch","validationCode":"u, err := url.Parse(remoteStr)\nif err != nil || u.Scheme == \"\" {\n    return fmt.Errorf(\"invalid engine remote %q\", remoteStr)\n}","typeGuard":null,"tryCatchPattern":"c, err := dagger.Connect(ctx)\nif err != nil {\n    if strings.Contains(err.Error(), \"buildkit client:\") {\n        // engine session unreachable/invalid; restart engine and retry\n        exec.Command(\"dagger\", \"engine\", \"restart\").Run()\n        c, err = dagger.Connect(ctx)\n    }\n    if err != nil { return err }\n}","preventionTips":["Keep dagger CLI and engine versions in sync","Don't hand-craft session endpoint URLs; let the SDK discover them","Check socket permissions and firewall rules in CI containers"],"tags":["buildkit","grpc","connection","engine-startup"],"backgroundTag":"buildkit-client-construction-failed","analyzedSha":"82ba2681dbe30d3547a1dc50ea495900ab5b6047","analyzedAt":"2026-09-05T07:21:37.930Z","contentChangedAt":"2026-09-05T07:21:37.930Z","schemaVersion":2},"datasetVersion":"2026-09-12T12:17:11.808Z"}