apache/shardingsphere · error · IllegalArgumentException

Either key generator name or algorithm segment must be provi

Error message

Either key generator name or algorithm segment must be provided.

What it means

IllegalArgumentException thrown by ShardingKeyGenerateStrategyStatementConverter.getKeyGeneratorName when a key-generate strategy segment in a DistSQL statement provides neither a keyGeneratorName nor an inline algorithmSegment. The converter must return a generator name; with both optionals empty there is nothing to name or construct, so it rejects the malformed statement.

Source

Thrown at features/sharding/distsql/handler/src/main/java/org/apache/shardingsphere/sharding/distsql/handler/converter/ShardingKeyGenerateStrategyStatementConverter.java:65

                : new SequenceKeyGenerateStrategiesRuleConfiguration(keyGeneratorName, ((SequenceKeyGenerateStrategyDefinitionSegment) keyGenerateStrategySegment).getSequenceName());
    }
    
    /**
     * Get key generator name.
     *
     * @param strategyName strategy name
     * @param keyGenerateStrategySegment key generate strategy segment
     * @return key generator name
     * @throws IllegalArgumentException when both key generator name and algorithm segment are absent
     */
    public static String getKeyGeneratorName(final String strategyName, final AbstractKeyGenerateStrategyDefinitionSegment keyGenerateStrategySegment) {
        if (keyGenerateStrategySegment.getKeyGeneratorName().isPresent()) {
            return keyGenerateStrategySegment.getKeyGeneratorName().get();
        }
        if (keyGenerateStrategySegment.getAlgorithmSegment().isPresent()) {
            return createKeyGeneratorName(strategyName, keyGenerateStrategySegment.getAlgorithmSegment().get());
        }
        throw new IllegalArgumentException("Either key generator name or algorithm segment must be provided.");
    }
    
    private static String createKeyGeneratorName(final String strategyName, final AlgorithmSegment algorithmSegment) {
        return String.format("%s_%s", strategyName, algorithmSegment.getName()).toLowerCase();
    }
}

View on GitHub (pinned to e952770a21)

Solutions

1. Provide either a named generator (KEY_GENERATOR_NAME(snowflake)) or an inline algorithm segment (GENERATED_KEY_ALGORITHM(NAME=uuid)) in the strategy.
2. If you do not want key generation for the table, remove the KEY_GENERATE_STRATEGY clause entirely.
3. Validate the DistSQL against the current grammar before applying.

Example fix

-- before: strategy lacks generator name and algorithm
CREATE SHARDING TABLE RULE t_order (
  DATANODES("ds_${0..1}.t_order_${0..3}"),
  SHARDING_COLUMN(order_id), TYPE(NAME=hash_mod, PROPERTIES("sharding-count"=4)),
  KEY_GENERATE_STRATEGY(COLUMN=order_id)
);

-- after: explicit generator
CREATE SHARDING TABLE RULE t_order (
  DATANODES("ds_${0..1}.t_order_${0..3}"),
  SHARDING_COLUMN(order_id), TYPE(NAME=hash_mod, PROPERTIES("sharding-count"=4)),
  KEY_GENERATE_STRATEGY(COLUMN=order_id, KEY_GENERATOR_NAME(snowflake))
);

// Validate a parsed key-generate strategy before submission
void validate(KeyGenerateStrategySegment s) {
    if (s.getKeyGeneratorName().isEmpty() && s.getAlgorithmSegment().isEmpty()) {
        throw new IllegalArgumentException("KEY_GENERATE_STRATEGY needs KEY_GENERATOR_NAME or GENERATED_KEY_ALGORITHM");
    }
}

boolean isCompleteKeyGenerateStrategy(final AbstractKeyGenerateStrategyDefinitionSegment s) {
    return s.getKeyGeneratorName().isPresent() || s.getAlgorithmSegment().isPresent();
}

try {
    getKeyGeneratorName(strategyName, segment);
} catch (final IllegalArgumentException ex) {
    // report which strategy is incomplete so the DistSQL can be fixed
}

When it happens

Trigger: CREATE/ALTER SHARDING TABLE RULE with a KEY_GENERATE_STRATEGY clause that specifies a column but omits both KEY_GENERATOR_NAME and the (GENERATED_KEY_ALGORITHM ...) segment; or a custom strategy definition segment parsed with both fields empty.

Common situations: Hand-written DistSQL with an incomplete KEY_GENERATE_STRATEGY; copy-paste from docs where the algorithm line was dropped; upgrading DistSQL syntax and losing the generator clause.

Related errors

• 1
• 1
• 0
• 12010
• 41

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