jackc/pgx · error

cannot use QueryExecModeCacheStatement with disabled…

Error message

cannot use QueryExecModeCacheStatement with disabled statement cache

What it means

Sentinel errDisabledStatementCache: QueryExecModeCacheStatement was selected as the default query execution mode, but the connection's statement cache was explicitly disabled (via DisablePreparedStatementCache or equivalent config). The mode requires the cache to store prepared statements, so pgx refuses the combination at query time.

Solutions

1. Pick a different QueryExecMode (e.g. QueryExecModeExec, QueryExecModeSimpleProtocol, or QueryExecModeCacheDescription)
2. Re-enable the statement cache if caching prepared statements is acceptable

When it happens

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

Appendix: source

Thrown at conn.go:130

func newProxyErr(background error, msg string) error {
	return &proxyError{
		msg:        msg,
		background: background,
	}
}

type proxyError struct {
	msg        string
	background error
}

func (err *proxyError) Error() string { return err.msg }

func (err *proxyError) Unwrap() error { return err.background }

var (
	errDisabledStatementCache   = fmt.Errorf("cannot use QueryExecModeCacheStatement with disabled statement cache")
	errDisabledDescriptionCache = fmt.Errorf("cannot use QueryExecModeCacheDescribe with disabled description cache")
)

// Connect establishes a connection with a PostgreSQL server with a connection string. See
// [pgconn.Connect] for details.
func Connect(ctx context.Context, connString string) (*Conn, error) {
	connConfig, err := ParseConfig(connString)
	if err != nil {
		return nil, err
	}
	return connect(ctx, connConfig)
}

// ConnectWithOptions behaves exactly like Connect with the addition of options. At the present options is only used to
// provide a [pgconn.GetSSLPasswordFunc] function.
func ConnectWithOptions(ctx context.Context, connString string, options ParseConfigOptions) (*Conn, error) {
	connConfig, err := ParseConfigWithOptions(connString, options)
	if err != nil {

View on GitHub (pinned to ec1a0befd2)