apache/shardingsphere · error · InvalidParameterValueException

CHARACTER SET %s is not defined

Error message

CHARACTER SET %s is not defined

What it means

InvalidParameterValueException ('CHARACTER SET %s is not defined') raised by FirebirdCharsetVariableProvider.parseCharset when resolving the Firebird SET NAMES-style variable. The value is trimmed and lowercased; 'default' maps to Charset.defaultCharset(), anything else must resolve through FirebirdCharacterSets.findCharacterSet; an unknown charset name throws IllegalArgumentException, which is converted to InvalidParameterValueException('names', value).

Source

Thrown at proxy/backend/dialect/firebird/src/main/java/org/apache/shardingsphere/proxy/backend/firebird/handler/admin/executor/variable/charset/FirebirdCharsetVariableProvider.java:44

import java.util.Locale;

/**
 * Charset variable provider of Firebird.
 */
public final class FirebirdCharsetVariableProvider implements CharsetVariableProvider {
    
    @Override
    public Collection<String> getCharsetVariables() {
        return Collections.singleton("names");
    }
    
    @Override
    public Charset parseCharset(final String variableValue) {
        String formattedValue = variableValue.trim().toLowerCase(Locale.ROOT);
        try {
            return "default".equals(formattedValue) ? Charset.defaultCharset() : FirebirdCharacterSets.findCharacterSet(formattedValue);
        } catch (final IllegalArgumentException ex) {
            throw new InvalidParameterValueException("names", formattedValue);
        }
    }
    
    @Override
    public String getDatabaseType() {
        return "Firebird";
    }
}

View on GitHub (pinned to e952770a21)

Solutions

1. Use a Firebird-recognized charset name (e.g. 'UTF8', 'NONE', 'WIN1252') or the literal 'default' for the names variable
2. Verify the exact accepted names in FirebirdCharacterSets for your ShardingSphere version and match the client encoding setting
3. Update the client driver's encoding property (e.g. Jaybird/FB JDBC 'encoding' parameter) to a supported value

Example fix

# before
jdbc:firebirdsql://host/db?encoding=utf-8

# after
jdbc:firebirdsql://host/db?encoding=UTF8

private static final Set<String> OK = Set.of("default", "utf8", "none", "win1252"); // per FirebirdCharacterSets
public void checkNames(final String value) {
    String v = value.trim().toLowerCase(Locale.ROOT);
    if (!OK.contains(v)) { throw new IllegalArgumentException("Unsupported Firebird names value: " + v); }
}

When it happens

Trigger: Connecting to the Firebird dialect proxy with a client charset/names value that is not 'default' and not present in the FirebirdCharacterSets catalog — e.g. 'utf9', 'utf8' when only firebird-specific names like 'utf8' variants/aliases known to the map are accepted, or a typo like 'latin1 ' handled but 'latn1' not.

Common situations: JDBC URL or client encoding not on Firebird's charset list (Firebird uses names like UTF8, NONE, WIN1252 rather than Java/IANA names in some clients); clients sending 'unicode' or 'ucs2'; case/typo issues in connection properties.

Related errors

• 1231
• invalid value for parameter "%s": "%s"
• 1253
• isc_charset_not_found
• Can not locate agent jar file by URL `%s`.

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