apache/shardingsphere · warning · UnsupportedVariableException

12010

12010

Error message

Can not support variable '%s'.

What it means

UnsupportedVariableException (error code 12010) thrown by SetDistVariableExecutor.getEnumType when the variable name given to SET DIST VARIABLE is neither a ConfigurationPropertyKey nor a TemporaryConfigurationPropertyKey enum constant (both looked up via valueOf(name.toUpperCase())). Only property keys known to these two enums can be set through SET DIST VARIABLE.

Source

Thrown at proxy/backend/core/src/main/java/org/apache/shardingsphere/proxy/backend/handler/distsql/ral/updatable/variable/SetDistVariableExecutor.java:56

/**
 * Set dist variable statement executor.
 */
public final class SetDistVariableExecutor implements DistSQLUpdateExecutor<SetDistVariableStatement> {
    
    @Override
    public void executeUpdate(final SetDistVariableStatement sqlStatement, final ContextManager contextManager) {
        ShardingSpherePreconditions.checkState(getEnumType(sqlStatement.getName()) instanceof TypedPropertyKey, () -> new UnsupportedVariableException(sqlStatement.getName()));
        handleConfigurationProperty(contextManager, (TypedPropertyKey) getEnumType(sqlStatement.getName()), sqlStatement.getValue());
    }
    
    private Enum<?> getEnumType(final String name) {
        try {
            return ConfigurationPropertyKey.valueOf(name.toUpperCase());
        } catch (final IllegalArgumentException ex) {
            try {
                return TemporaryConfigurationPropertyKey.valueOf(name.toUpperCase());
            } catch (final IllegalArgumentException exception) {
                throw new UnsupportedVariableException(name);
            }
        }
    }
    
    private void handleConfigurationProperty(final ContextManager contextManager, final TypedPropertyKey propertyKey, final String value) {
        MetaDataContexts metaDataContexts = contextManager.getMetaDataContexts();
        Properties props = new Properties();
        props.putAll(metaDataContexts.getMetaData().getProps().getProps());
        props.putAll(metaDataContexts.getMetaData().getTemporaryProps().getProps());
        props.put(propertyKey.getKey(), getValue(propertyKey, value));
        contextManager.getPersistServiceFacade().getModeFacade().getMetaDataManagerService().alterProperties(props);
    }
    
    private Object getValue(final TypedPropertyKey propertyKey, final String value) {
        try {
            Object propertyValue = new TypedPropertyValue(propertyKey, value).getValue();
            checkProxyMetaDataCollectorCron(propertyKey, value);
            if (Enum.class.isAssignableFrom(propertyKey.getType())) {

View on GitHub (pinned to e952770a21)

Solutions

1. Check the property name against the version's ConfigurationPropertyKey / TemporaryConfigurationPropertyKey lists (see proxy props documentation) and correct spelling/case
2. For properties not settable via DistSQL, edit server.yaml (or the mode repository) and restart/refresh instead
3. Upgrade to a version where the desired property is exposed as a settable key

Example fix

-- before
SET DIST VARIABLE WHERE NAME = 'max_pool_size' AND VALUE = '20';

-- after (use the real storage-unit pool config, not DIST VARIABLE, or a valid key)
ALTER RESOURCE ... ;
-- or, for a supported key:
SET DIST VARIABLE WHERE NAME = 'sql_show' AND VALUE = 'true';

private static final Set<String> SETTABLE = Stream.concat(
        Arrays.stream(ConfigurationPropertyKey.values()).map(Enum::name),
        Arrays.stream(TemporaryConfigurationPropertyKey.values()).map(Enum::name))
    .map(String::toLowerCase).collect(Collectors.toSet());

public void assertSettable(final String name) {
    if (!SETTABLE.contains(name.toLowerCase())) {
        throw new IllegalArgumentException("Not a settable DIST VARIABLE: " + name);
    }
}

When it happens

Trigger: SET DIST VARIABLE WHERE NAME = '<name>' where <name>.toUpperCase() matches no constant in ConfigurationPropertyKey (e.g. sql-show, max-connections-size-per-query) and no constant in TemporaryConfigurationPropertyKey (e.g. proxy_meta_data_collector_cron); valueOf throws IllegalArgumentException in both attempts.

Common situations: Trying to set variables that only exist in server.yaml but are not enum members; typos or wrong case in the property name; attempting to set transaction rule or storage-unit attributes (not configuration properties) via SET DIST VARIABLE; version differences where a property key was added later.

Related errors

• 12010
• 12011
• Either key generator name or algorithm segment must be provi
• 0
• 1

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