What causes "CHARACTER SET %s is not defined" in apache/shardingsphere?

Set the client encoding to a well-supported value such as UTF8 or NONE in the connection properties (e.g. Jaybird encoding=UTF8).

apache/shardingsphere · error · InvalidParameterValueException

isc_charset_not_found

isc_charset_not_found

Error message

CHARACTER SET %s is not defined

What it means

Firebird vendor error isc_charset_not_found ('CHARACTER SET %s is not defined'). During Firebird ATTACH, parseAttachCharset() resolves the encoding string from the attach packet via FirebirdCharacterSets.findCharacterSet(encoding); an unknown encoding raises IllegalArgumentException, which the engine converts to InvalidParameterValueException('lc_ctype', encoding). FirebirdDialectExceptionMapper maps that to FirebirdVendorError.CHARSET_NOT_FOUND so the client sees the native Firebird error.

Source

Thrown at proxy/frontend/dialect/firebird/src/main/java/org/apache/shardingsphere/proxy/frontend/firebird/authentication/FirebirdAuthenticationEngine.java:124

        }
    }
    
    private AuthenticationResult processAttach(final ChannelHandlerContext context, final FirebirdPacketPayload payload, final AuthorityRule rule) {
        FirebirdAttachPacket attachPacket = new FirebirdAttachPacket(payload);
        context.channel().attr(CommonConstants.CHARSET_ATTRIBUTE_KEY).set(parseAttachCharset(attachPacket.getEncoding()));
        login(currentAuthResult.getDatabase(), currentAuthResult.getUsername(), attachPacket, rule);
        context.writeAndFlush(new FirebirdGenericResponsePacket());
        return AuthenticationResultBuilder.finished(currentAuthResult.getUsername(), "", currentAuthResult.getDatabase(), currentAuthResult.getConnectionAttributes());
    }
    
    private Charset parseAttachCharset(final String encoding) {
        if (null == encoding) {
            return FirebirdCharacterSets.findCharacterSet("NONE");
        }
        try {
            return FirebirdCharacterSets.findCharacterSet(encoding);
        } catch (final IllegalArgumentException ex) {
            throw new InvalidParameterValueException("lc_ctype", encoding);
        }
    }
    
    private void login(final String databaseName, final String username, final FirebirdAttachPacket attachPacket, final AuthorityRule rule) {
        ShardingSpherePreconditions.checkState(
                Strings.isNullOrEmpty(databaseName) || ProxyContext.getInstance().getContextManager().getMetaDataContexts().getMetaData().containsDatabase(databaseName),
                () -> new UnknownDatabaseException(databaseName));
        Grantee grantee = new Grantee(username, "");
        ShardingSphereUser user = rule.findUser(grantee).orElseThrow(() -> new AccessDeniedException(username, "", true));
        boolean authenticated = new AuthenticatorFactory<>(FirebirdAuthenticatorType.class, rule)
                .newInstance(user).authenticate(user, new Object[]{attachPacket.getEncPassword(), authData, attachPacket.getAuthData()});
        ShardingSpherePreconditions.checkState(authenticated, () -> new AccessDeniedException(username, "", true));
    }
    
    private AuthenticationResult processConnect(final ChannelHandlerContext context, final FirebirdPacketPayload payload, final AuthorityRule rule) {
        FirebirdConnectPacket connectPacket = new FirebirdConnectPacket(payload);
        FirebirdAcceptPacket acceptPacket = new FirebirdAcceptPacket(connectPacket.getUserProtocols());
        context.channel().attr(CommonConstants.CHARSET_ATTRIBUTE_KEY).set(FirebirdCharacterSets.findCharacterSet("NONE"));

View on GitHub (pinned to e952770a21)

Solutions

Set the client encoding to a well-supported value such as UTF8 or NONE in the connection properties (e.g. Jaybird encoding=UTF8).
If a specific Firebird charset is required, check FirebirdCharacterSets for the supported name mapping and use exactly that spelling (case-sensitive lookup of normalized names).
Omit lc_ctype entirely to get the 'NONE' default, then transcode on the client side.
If the charset is genuinely required for your locale, request support or extend the FirebirdCharacterSets map in the proxy backend module.

Example fix

// before (Jaybird)
props.put("encoding", "WIN1257");

// after
props.put("encoding", "UTF8");

Defensive patterns

Strategy: validation

Validate before calling

// Client: whitelist encodings before connecting
String enc = props.getProperty("encoding", "NONE");
if (!Set.of("NONE", "UTF8", "ASCII", "ISO8859_1").contains(enc.toUpperCase())) {
    throw new IllegalArgumentException("Unsupported encoding: " + enc);
}

Try / catch

catch (SQLTransientException e) {
    // isc_charset_not_found arrives as an SQL error; fix encoding and reconnect
    props.setProperty("encoding", "UTF8");
    reconnect();
}

Prevention

Always set encoding=UTF8 explicitly instead of relying on locale defaults.
Do not invent charset names; use names the backend/proxy character-set map defines.

When it happens

Trigger: A client attaches with an lc_ctype/encoding clumplet whose value is not a key in the FirebirdCharacterSets map (for example an exotic Firebird collation charset not backed by a Java Charset). null encoding is fine (defaults to 'NONE'); only unknown non-null names fail.

Common situations: client dpb/lc_ctype set to a charset the proxy does not map (e.g. WIN1251 variants without Java equivalents, or a typo like 'UTF-8' with a dash); Jaybird connection property charSet or encoding set to a value valid in real Firebird but unmapped in ShardingSphere; locale-specific defaults from old client tools.

Related errors

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