jackc/pgx · error

EscapeString must be run with client_encoding=UTF8

Error message

EscapeString must be run with client_encoding=UTF8

What it means

EscapeString only supports client_encoding=UTF8; the connection's client_encoding parameter status was something other than UTF8, so escaping cannot safely proceed. Ensure the connection uses UTF8 (the default for most setups) before calling EscapeString.

Solutions

1. Set client_encoding=UTF8 on the connection (or leave the default)
2. Pass the escaping work to the server via parameterized queries instead

When it happens

Trigger: Thrown at pgconn/pgconn.go:2073 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/cef70cfbcc703788. Report an issue: GitHub.

Appendix: source

Thrown at pgconn/pgconn.go:2073

		pgConn.asyncClose()
		return multiResult
	}

	return multiResult
}

// EscapeString escapes a string such that it can safely be interpolated into a SQL command string. It does not include
// the surrounding single quotes.
//
// The current implementation requires that standard_conforming_strings=on and client_encoding="UTF8". If these
// conditions are not met an error will be returned. It is possible these restrictions will be lifted in the future.
func (pgConn *PgConn) EscapeString(s string) (string, error) {
	if pgConn.ParameterStatus("standard_conforming_strings") != "on" {
		return "", errors.New("EscapeString must be run with standard_conforming_strings=on")
	}

	if pgConn.ParameterStatus("client_encoding") != "UTF8" {
		return "", errors.New("EscapeString must be run with client_encoding=UTF8")
	}

	return strings.ReplaceAll(s, "'", "''"), nil
}

// CheckConn checks the underlying connection without writing any bytes. This is currently implemented by doing a read
// with a very short deadline. This can be useful because a TCP connection can be broken such that a write will appear
// to succeed even though it will never actually reach the server. Reading immediately before a write will detect this
// condition. If this is done immediately before sending a query it reduces the chances a query will be sent that fails
// without the client knowing whether the server received it or not.
//
// Deprecated: CheckConn is deprecated in favor of Ping. CheckConn cannot detect all types of broken connections where
// the write would still appear to succeed. Prefer Ping unless on a high latency connection.
func (pgConn *PgConn) CheckConn() error {
	ctx, cancel := context.WithTimeout(context.Background(), 1*time.Millisecond)
	defer cancel()

	_, err := pgConn.ReceiveMessage(ctx)

View on GitHub (pinned to ec1a0befd2)