apache/shardingsphere · error · InvalidParameterValueException

invalid value for parameter "%s": "%s"

Error message

invalid value for parameter "%s": "%s"

What it means

InvalidParameterValueException ('invalid value for parameter "client_encoding": "%s"', matching PostgreSQL's own error shape) thrown by PostgreSQLCharsetVariableProvider.parseCharset when the client_encoding value is anything other than 'default', 'utf8', 'utf-8', 'utf_8', or 'unicode' (after lowercasing and quote stripping). The ShardingSphere PostgreSQL proxy only implements UTF-8 client encoding, so every other encoding request is rejected.

Source

Thrown at proxy/backend/dialect/postgresql/src/main/java/org/apache/shardingsphere/proxy/backend/postgresql/handler/admin/executor/variable/charset/PostgreSQLCharsetVariableProvider.java:46

import java.util.Locale;

/**
 * Charset variable provider of PostgreSQL.
 */
public final class PostgreSQLCharsetVariableProvider implements CharsetVariableProvider {
    
    @Override
    public Collection<String> getCharsetVariables() {
        return Collections.singleton("client_encoding");
    }
    
    @Override
    public Charset parseCharset(final String variableValue) {
        String formattedValue = formatValue(variableValue).toLowerCase(Locale.ROOT);
        boolean isDefault = "default".equals(formattedValue);
        boolean isUtf8 = "utf8".equals(formattedValue) || "utf-8".equals(formattedValue) || "utf_8".equals(formattedValue) || "unicode".equals(formattedValue);
        if (!isDefault && !isUtf8) {
            throw new InvalidParameterValueException("client_encoding", formattedValue);
        }
        return StandardCharsets.UTF_8;
    }
    
    private String formatValue(final String value) {
        return QuoteCharacter.SINGLE_QUOTE.isWrapped(value) || QuoteCharacter.QUOTE.isWrapped(value) ? value.substring(1, value.length() - 1).trim() : value.trim();
    }
    
    @Override
    public String getDatabaseType() {
        return "PostgreSQL";
    }
}

View on GitHub (pinned to e952770a21)

Solutions

1. Configure the client to use UTF-8: set PGCLIENTENCODING=UTF8, pass ?options=-c client_encoding=utf8, or set the driver's charSet/encoding property to UTF-8
2. Change the client terminal/locale to UTF-8 so psql does not request a legacy encoding
3. If a non-UTF8 encoding is a hard requirement, it is unsupported by the proxy — terminate the encoding conversion in the application instead

Example fix

# before
PGCLIENTENCODING=LATIN1 psql -h proxy -p 3307 -d demo

# after
PGCLIENTENCODING=UTF8 psql -h proxy -p 3307 -d demo

private static final Set<String> SUPPORTED = Set.of("default", "utf8", "utf-8", "utf_8", "unicode");
public void checkClientEncoding(final String value) {
    String v = value.trim().toLowerCase(Locale.ROOT);
    if (!SUPPORTED.contains(v)) { throw new IllegalArgumentException("Only UTF-8 client_encoding is supported: " + v); }
}

When it happens

Trigger: A PostgreSQL client issuing SET client_encoding TO 'LATIN1' / 'WIN1252' / 'SQL_ASCII' etc. during connection setup or a session; formatValue strips single/double quotes, and anything not in the UTF-8 alias set throws InvalidParameterValueException('client_encoding', value).

Common situations: Legacy clients or drivers configured for LATIN1/EUC-JP connecting through the proxy; psql clients inheriting a non-UTF8 locale issuing SET client_encoding; GUI tools that probe/force encodings on connect.

Related errors

• CHARACTER SET %s is not defined
• Unsupported PostgreSQL format code `%s`
• 1253
• 1231
• Missing required format info in createBatch()

AI-assisted analysis of apache/shardingsphere@e952770a21 (2026-08-14). Data as JSON: /api/errors/04711f1f33de0dc2. Report an issue: GitHub.