Validating Commands with Interceptors

A MessageDispatchInterceptor<CommandMessage<?>> implements a single handle method that returns a function applied to every command as it's dispatched. Inside that function, you inspect the command's payload — often with a type check against a specific command class, when the rule only applies to certain command types — and either let it through unchanged or throw to reject it outright, before it ever reaches an aggregate.

Writing the interceptor class alone isn't enough — it also has to be explicitly registered with the CommandBus, typically inside a @Configuration class, injecting both the CommandBus and the interceptor and calling registerDispatchInterceptor() once at startup. Without this registration step, the interceptor class exists, compiles cleanly, and simply never runs, since Axon has no way to discover it on its own.

The distinction in scope between this and aggregate-level validation matters. An interceptor runs centrally, once, regardless of which aggregate the command is ultimately headed to — ideal for cross-cutting, stateless checks. Business rules that depend on an aggregate's own current state — "you can't withdraw more than the current balance" — can only be checked inside the aggregate itself, since only the aggregate, rebuilt from its own event history, actually knows its own current state. Use interceptors for universal, stateless checks; use the aggregate for anything that depends on the aggregate's own data.

@Component
public class CommandValidationInterceptor implements MessageDispatchInterceptor<CommandMessage<?>> {

    @Override
    public BiFunction<Integer, CommandMessage<?>, CommandMessage<?>> handle(List<? extends CommandMessage<?>> messages) {
        return (index, command) -> {
            Object payload = command.getPayload();
            if (payload instanceof CreateCustomerCommand cmd) {
                if (cmd.getCustomerId() == null || cmd.getCustomerId().isBlank()) {
                    throw new IllegalArgumentException("customerId is required on every command");
                }
            }
            return command; // unchanged and allowed through, on to the aggregate
        };
    }
}

@Configuration
public class AxonConfig {

    @Autowired
    public void registerInterceptor(CommandBus commandBus, CommandValidationInterceptor interceptor) {
        commandBus.registerDispatchInterceptor(interceptor);
    }
}

The single most common mistake with dispatch interceptors is exactly the one already flagged: writing the interceptor class, having it compile fine, and forgetting the registration step. Because there's no compile-time link forcing you to register it, this failure is silent — commands that should be rejected sail through untouched, and nothing in the logs points at a missing registration line. Always confirm a new interceptor is actually firing — a simple log line inside it while testing is enough — rather than assuming it works just because the class compiled.

A second mistake is putting a check inside an interceptor that actually needs an aggregate's current state to evaluate correctly. An interceptor runs before any aggregate is loaded, so it has no access to that aggregate's fields at all — trying to check something like "does this customer already exist" inside an interceptor either requires an extra, separate lookup (adding real complexity and a potential race condition against the aggregate's own state) or simply can't be done correctly there. That category of check belongs inside the aggregate's command handler instead, where the current state is already available after replay.

A third, more subtle mistake is stacking too much unrelated logic into one interceptor. Since one interceptor runs on every command in the system, cramming validation for many unrelated command types into a single class makes it a growing, hard-to-navigate bottleneck. Splitting checks across several focused interceptors, each registered independently, tends to stay more maintainable as a system grows.