{"record":{"id":"da76c28ea371ca0d","repo":"thanos-io/thanos","slug":"failed-to-bootstrap-capnp-writer","errorCode":null,"errorMessage":"failed to bootstrap capnp writer","messagePattern":"failed to bootstrap capnp writer","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/receive/writecapnp/client.go","lineNumber":213,"sourceCode":"}\n\nfunc (r *RemoteWriteClient) connect(ctx context.Context) error {\n\tr.mu.Lock()\n\tdefer r.mu.Unlock()\n\tif r.conn != nil {\n\t\treturn nil\n\t}\n\n\tconn, err := r.dialer.DialContext(ctx)\n\tif err != nil {\n\t\treturn errors.Wrap(err, \"failed to dial peer\")\n\t}\n\tr.conn = rpc.NewConn(rpc.NewPackedStreamTransport(conn), nil)\n\twriter := Writer(r.conn.Bootstrap(ctx))\n\tif err := writer.Resolve(ctx); err != nil {\n\t\tlevel.Warn(r.logger).Log(\"msg\", \"failed to bootstrap capnp writer, closing connection\", \"err\", err)\n\t\tr.closeUnlocked()\n\t\treturn errors.Wrap(err, \"failed to bootstrap capnp writer\")\n\t}\n\n\tr.writer = writer\n\treturn nil\n}\n\nfunc (r *RemoteWriteClient) Close() error {\n\tr.mu.Lock()\n\tr.closeUnlocked()\n\tr.mu.Unlock()\n\treturn nil\n}\n\nfunc (r *RemoteWriteClient) closeUnlocked() {\n\tif r.conn != nil {\n\t\tconn := r.conn\n\t\tr.conn = nil\n\t\tgo conn.Close()","sourceCodeStart":195,"sourceCodeEnd":231,"githubUrl":"https://github.com/thanos-io/thanos/blob/35b8b991177def87ed52dcf10f9b6d87f07282c8/pkg/receive/writecapnp/client.go#L195-L231","documentation":"connect() dials a capnp connection and bootstraps the remote Writer capability. After NewConn, it obtains the bootstrap capability via r.conn.Bootstrap(ctx) and calls writer.Resolve(ctx); if the remote side fails to serve the bootstrap interface (or the context dies before resolution), the connection is torn down and this wrapped error is returned.","triggerScenarios":"The remote capnp server (Cortex receiver) did not answer the bootstrap RPC within ctx's deadline, the remote returned an exception for the bootstrap capability, the connection was reset immediately after dial, or ctx was canceled before Resolve completed.","commonSituations":"Remote receiver not actually a capnp server on that port; wrong port in config; receiver overloaded or restarting; network firewall silently dropping the stream; context timeout too short under load.","solutions":["Check the receiver address/port in the receive config points at the capnp writer endpoint and that the remote service is up","Increase the context timeout passed to connect/writeWithReconnect","Verify network connectivity (firewalls, load balancers) between sender and receiver","Retry the write — writeWithReconnect will re-dial; ensure reconnect backoff is enabled","Check receiver logs for bootstrap/rpc errors at the same timestamp"],"exampleFix":"// before\nctx := context.Background()\nerr := client.Write(ctx, req) // hangs until some inner timeout, then bootstrap fails\n// after\nctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)\ndefer cancel()\nerr := client.Write(ctx, req)","handlingStrategy":"retry","validationCode":"// before writing, verify the endpoint is reachable\nconn, err := net.DialTimeout(\"tcp\", addr, 5*time.Second)\nif err != nil { return fmt.Errorf(\"capnp endpoint %s unreachable: %w\", addr, err) }\nconn.Close()","typeGuard":null,"tryCatchPattern":"var be *errors.Error\nif errors.As(err, &be) && strings.Contains(be.Error(), \"failed to bootstrap capnp writer\") {\n    // re-dial with backoff; check ctx deadline first\n    select { case <-ctx.Done(): return ctx.Err(); default: }\n    time.Sleep(backoff)\n    return retry()\n}","preventionTips":["Use a context timeout that exceeds expected dial+bootstrap time","Health-check the receiver before enabling writes","Enable writeWithReconnect with exponential backoff","Monitor receiver availability/logs for bootstrap failures"],"tags":["capnp","network","rpc","connection"],"backgroundTag":"connection-refused","analyzedSha":"35b8b991177def87ed52dcf10f9b6d87f07282c8","analyzedAt":"2026-09-07T01:49:59.689Z","contentChangedAt":"2026-09-07T01:49:59.689Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}