apache/shardingsphere · error · AlgorithmInitializationException

Algorithm '%s' initialization failed, reason is: %s must be

Error message

Algorithm '%s' initialization failed, reason is: %s must be a valid integer number.

What it means

Thrown by MaskAlgorithmPropertiesChecker.checkPositiveInteger when a required mask algorithm property exists but its value cannot be parsed by Integer.parseInt. It is wrapped in AlgorithmInitializationException, so the whole mask algorithm (and rule activation) fails at init time with a message naming the property key that must be a valid integer.

Source

Thrown at features/mask/core/src/main/java/org/apache/shardingsphere/mask/algorithm/MaskAlgorithmPropertiesChecker.java:72

        checkRequired(props, propKey, algorithm);
        ShardingSpherePreconditions.checkNotEmpty(props.getProperty(propKey), () -> new AlgorithmInitializationException(algorithm, "%s's length must be at least one", propKey));
    }
    
    /**
     * check positive integer.
     *
     * @param props properties to be checked
     * @param propKey properties key to be checked
     * @param algorithm mask algorithm
     * @throws AlgorithmInitializationException algorithm initialization exception
     */
    public static void checkPositiveInteger(final Properties props, final String propKey, final MaskAlgorithm<?, ?> algorithm) {
        checkRequired(props, propKey, algorithm);
        try {
            int integerValue = Integer.parseInt(props.getProperty(propKey));
            ShardingSpherePreconditions.checkState(integerValue > 0, () -> new AlgorithmInitializationException(algorithm, "%s must be a positive integer.", propKey));
        } catch (final NumberFormatException ex) {
            throw new AlgorithmInitializationException(algorithm, "%s must be a valid integer number", propKey);
        }
    }
    
    private static void checkRequired(final Properties props, final String requiredPropKey, final MaskAlgorithm<?, ?> algorithm) {
        ShardingSpherePreconditions.checkContainsKey(props, requiredPropKey, () -> new AlgorithmInitializationException(algorithm, "%s is required", requiredPropKey));
    }
}

View on GitHub (pinned to e952770a21)

Solutions

Set the named property to a plain positive integer string, e.g. from_x: 5
Remove any quotes, spaces, or non-numeric characters around the value in YAML
If a fractional value seems needed, re-read the algorithm's docs - these properties are character positions/counts and must be whole numbers
Restart or re-activate the mask rule so the algorithm re-initializes with corrected props

Example fix

# before
- !MASK_ALGORITHM_FROM_X_TO_Y
  props:
    from_x: 'abc'
    to_x: '#'
# after
- !MASK_ALGORITHM_FROM_X_TO_Y
  props:
    from_x: 5
    to_x: '#'

Defensive patterns

Strategy: validation

Validate before calling

String v = props.getProperty(propKey);
if (v == null || !v.matches("\\d+")) throw new IllegalArgumentException(propKey + " must be a positive integer, got: " + v);

Prevention

Validate mask algorithm props in CI with a YAML schema/lint step
Quote numeric props consistently in YAML templates

When it happens

Trigger: Configuring a mask algorithm such as MASK_FROM_X_TO_Y or similar with a property like from_x / to_x / replace_char-x whose value is non-numeric (e.g. 'abc', '1.5', empty, or unquoted special characters) in the MASK rule props.

Common situations: YAML quoting mistakes where a number is stored as a string with whitespace; copy-paste from docs with placeholder text; passing a float like '0.5' where an integer index is required; locale/format confusion after config migration.

Related errors

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