jackc/pgx · error

failed to deallocate previously failed statement

Error message

failed to deallocate previously failed statement %q: %w

What it means

During connection close, pgx attempted to deallocate a prepared statement that previously failed, and the DEALLOCATE itself returned an error (wrapped with %w). This occurs in cleanup paths where an earlier statement failure invalidated the statement and close-time cleanup also failed.

Solutions

1. Inspect the wrapped error to find the underlying server or network failure
2. If the connection is already broken, the deallocation failure is moot — the server discards statements on disconnect
3. Retry Close on a still-usable connection or log and continue if the underlying cause is a dead connection

When it happens

Trigger: Thrown at conn.go:324 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of jackc/pgx@ec1a0befd2 (2026-08-04). Data as JSON: /api/errors/4f32b8a8e78375df. Report an issue: GitHub.

Appendix: source

Thrown at conn.go:324

	err := c.pgConn.Close(ctx)
	return err
}

// Prepare creates a prepared statement with name and sql. sql can contain placeholders for bound parameters. These
// placeholders are referenced positionally as $1, $2, etc. name can be used instead of sql with [Conn.Query],
// [Conn.QueryRow], and [Conn.Exec] to execute the statement. It can also be used with [Batch.Queue].
//
// The underlying PostgreSQL identifier for the prepared statement will be name if name != sql or a digest of sql if
// name == sql.
//
// Prepare is idempotent; i.e. it is safe to call Prepare multiple times with the same name and sql arguments. This
// allows a code path to Prepare and Query/Exec without concern for if the statement has already been prepared.
func (c *Conn) Prepare(ctx context.Context, name, sql string) (sd *pgconn.StatementDescription, err error) {
	if c.failedDescribeStatement != "" {
		err = c.Deallocate(ctx, c.failedDescribeStatement)
		if err != nil {
			return nil, fmt.Errorf("failed to deallocate previously failed statement %q: %w", c.failedDescribeStatement, err)
		}
		c.failedDescribeStatement = ""
	}

	if c.prepareTracer != nil {
		ctx = c.prepareTracer.TracePrepareStart(ctx, c, TracePrepareStartData{Name: name, SQL: sql})
	}

	if name != "" {
		var ok bool
		if sd, ok = c.preparedStatements[name]; ok && sd.SQL == sql {
			if c.prepareTracer != nil {
				c.prepareTracer.TracePrepareEnd(ctx, c, TracePrepareEndData{AlreadyPrepared: true})
			}
			return sd, nil
		}
	}

View on GitHub (pinned to ec1a0befd2)