{"record":{"id":"5334259253c7961a","repo":"jackc/pgx","slug":"syncconn-ping-failed-while-syncing-conn-w","errorCode":null,"errorMessage":"SyncConn: Ping failed while syncing conn: %w","messagePattern":"SyncConn: Ping failed while syncing conn: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pgconn/pgconn.go","lineNumber":2163,"sourceCode":"\treturn err\n}\n\n// SyncConn prepares the underlying net.Conn for direct use. PgConn may internally buffer reads or use goroutines for\n// background IO. This means that any direct use of the underlying net.Conn may be corrupted if a read is already\n// buffered or a read is in progress. SyncConn drains read buffers and stops background IO. In some cases this may\n// require sending a ping to the server. ctx can be used to cancel this operation. This should be called before any\n// operation that will use the underlying net.Conn directly. e.g. Before Conn() or Hijack().\n//\n// This should not be confused with the PostgreSQL protocol Sync message.\nfunc (pgConn *PgConn) SyncConn(ctx context.Context) error {\n\tfor range 10 {\n\t\tif pgConn.bgReader.Status() == bgreader.StatusStopped && pgConn.frontend.ReadBufferLen() == 0 {\n\t\t\treturn nil\n\t\t}\n\n\t\terr := pgConn.Ping(ctx)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"SyncConn: Ping failed while syncing conn: %w\", err)\n\t\t}\n\t}\n\n\t// This should never happen. Only way I can imagine this occurring is if the server is constantly sending data such as\n\t// LISTEN/NOTIFY or log notifications such that we never can get an empty buffer.\n\treturn errors.New(\"SyncConn: conn never synchronized\")\n}\n\n// CustomData returns a map that can be used to associate custom data with the connection.\nfunc (pgConn *PgConn) CustomData() map[string]any {\n\treturn pgConn.customData\n}\n\n// HijackedConn is the result of hijacking a connection.\n//\n// Due to the necessary exposure of internal implementation details, it is not covered by the semantic versioning\n// compatibility.\ntype HijackedConn struct {","sourceCodeStart":2145,"sourceCodeEnd":2181,"githubUrl":"https://github.com/jackc/pgx/blob/ec1a0befd22592cffffdeeb0a50311b506372f4c/pgconn/pgconn.go#L2145-L2181","documentation":"SyncConn needed to drain the connection's state before handing the raw net.Conn to the caller, which required a Ping, and that Ping failed. The connection's readiness for direct use could not be confirmed.","triggerScenarios":"Thrown at pgconn/pgconn.go:2163 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Check the wrapped Ping error for the underlying cause","Verify the connection is still alive before calling SyncConn","Retry SyncConn if the failure was transient","Ensure no concurrent operations are using the connection"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"ec1a0befd22592cffffdeeb0a50311b506372f4c","analyzedAt":"2026-08-04T22:52:11.263Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}