jackc/pgx · error

failed to deallocate cached statement(s)

Error message

failed to deallocate cached statement(s): %w

What it means

After query execution, pgx tried to deallocate cached statements that had been invalidated (e.g. by a schema change), but the pipeline Sync or Close failed. The underlying pipeline error is wrapped with %w; cached statements may remain allocated server-side.

Solutions

1. Unwrap to inspect the underlying pipeline error
2. If the connection is healthy, retry the operation that triggered invalidation so cleanup re-runs
3. If the connection is closing or dead, the server cleans up statements on disconnect — safe to ignore

When it happens

Trigger: Thrown at conn.go:1462 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/d4f043631903b9ed. Report an issue: GitHub.

Appendix: source

Thrown at conn.go:1462

	var invalidatedStatements []*pgconn.StatementDescription
	if c.statementCache != nil {
		invalidatedStatements = c.statementCache.GetInvalidated()
	}

	if len(invalidatedStatements) == 0 {
		return nil
	}

	pipeline := c.pgConn.StartPipeline(ctx)
	defer pipeline.Close()

	for _, sd := range invalidatedStatements {
		pipeline.SendDeallocate(sd.Name)
	}

	err := pipeline.Sync()
	if err != nil {
		return fmt.Errorf("failed to deallocate cached statement(s): %w", err)
	}

	err = pipeline.Close()
	if err != nil {
		return fmt.Errorf("failed to deallocate cached statement(s): %w", err)
	}

	c.statementCache.RemoveInvalidated()
	for _, sd := range invalidatedStatements {
		delete(c.preparedStatements, sd.Name)
	}

	return nil
}

View on GitHub (pinned to ec1a0befd2)