Netflix/Hystrix · error · IllegalStateException

HystrixCommandGroup can not be NULL

Error message

HystrixCommandGroup can not be NULL

What it means

Hystrix requires every command to belong to a HystrixCommandGroupKey; the AbstractCommand constructor validates this in initGroupKey and throws IllegalStateException when the group key passed in is null. The group key is used primarily for reporting/alerting grouping (thread pools are keyed by commandKey or threadPoolKey).

Source

Thrown at hystrix-core/src/main/java/com/netflix/hystrix/AbstractCommand.java:188

        //Strategies from plugins
        this.eventNotifier = HystrixPlugins.getInstance().getEventNotifier();
        this.concurrencyStrategy = HystrixPlugins.getInstance().getConcurrencyStrategy();
        HystrixMetricsPublisherFactory.createOrRetrievePublisherForCommand(this.commandKey, this.commandGroup, this.metrics, this.circuitBreaker, this.properties);
        this.executionHook = initExecutionHook(executionHook);

        this.requestCache = HystrixRequestCache.getInstance(this.commandKey, this.concurrencyStrategy);
        this.currentRequestLog = initRequestLog(this.properties.requestLogEnabled().get(), this.concurrencyStrategy);

        /* fallback semaphore override if applicable */
        this.fallbackSemaphoreOverride = fallbackSemaphore;

        /* execution semaphore override if applicable */
        this.executionSemaphoreOverride = executionSemaphore;
    }

    private static HystrixCommandGroupKey initGroupKey(final HystrixCommandGroupKey fromConstructor) {
        if (fromConstructor == null) {
            throw new IllegalStateException("HystrixCommandGroup can not be NULL");
        } else {
            return fromConstructor;
        }
    }

    private static HystrixCommandKey initCommandKey(final HystrixCommandKey fromConstructor, Class<?> clazz) {
        if (fromConstructor == null || fromConstructor.name().trim().equals("")) {
            final String keyName = getDefaultNameFromClass(clazz);
            return HystrixCommandKey.Factory.asKey(keyName);
        } else {
            return fromConstructor;
        }
    }

    private static HystrixCommandProperties initCommandProperties(HystrixCommandKey commandKey, HystrixPropertiesStrategy propertiesStrategy, HystrixCommandProperties.Setter commandPropertiesDefaults) {
        if (propertiesStrategy == null) {
            return HystrixPropertiesFactory.getCommandProperties(commandKey, commandPropertiesDefaults);
        } else {

View on GitHub (pinned to 5ce3bc58c3)

Solutions

1. Pass a non-null HystrixCommandGroupKey.Factory.asKey("GroupName") to the command constructor
2. If a group genuinely does not apply, define a synthetic grouping key (e.g. the same string as the commandKey) rather than null
3. Add a unit test asserting every command subclass constructor forwards a non-null group key

Example fix

// before
new HystrixCommand<String>(null) { protected String run() { return "x"; } };
// after
new HystrixCommand<String>(HystrixCommandGroupKey.Factory.asKey("OrderService")) { protected String run() { return "x"; } };

HystrixCommandGroupKey group = HystrixCommandGroupKey.Factory.asKey("OrderService");
if (group == null || group.name() == null) throw new IllegalArgumentException("group key required");

// Java: null-check the key before constructing the command
static boolean isValidGroupKey(HystrixCommandGroupKey k) { return k != null && k.name() != null && !k.name().trim().isEmpty(); }

Not productive to catch — validate inputs before constructing; an IllegalStateException here is a programming error surfaced at construction time.

When it happens

Trigger: Constructing new HystrixCommand(null) or new HystrixObservableCommand(null), or calling HystrixCommand.Factory with a null group while also omitting a threadPoolKey path that would otherwise not need it; also subclass constructors that forward a null group field.

Common situations: Refactoring removes the group-key constant and passes null by mistake; copy-paste constructor calls where the group argument was deleted; migrating from HystrixCommand(group) to builder-style APIs and forgetting to set the group.

Related errors

• You have set the bucket size to 0ms. Please set a positive
• Failed to set Thread Pool properties. {}
• Failed to set Command properties. {}
• unknown {} property: {}
• bad property value. property name '{}'. Expected int value,

AI-assisted analysis of Netflix/Hystrix@5ce3bc58c3 (2026-08-14). Data as JSON: /api/errors/ea272510daad733e. Report an issue: GitHub.