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.

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
• 0
• Either key generator name or algorithm segment must be…
• 1

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

Appendix: 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)