flowable/flowable-engine · error · FlowableIllegalArgumentException

Channel definition id is null

Error message

Channel definition id is null

What it means

SetChannelDefinitionCategoryCmd.execute() validates that a channel definition id was supplied; if channelDefinitionId is null it throws FlowableIllegalArgumentException before querying. The category of an existing channel definition cannot be changed without identifying it by id.

Source

Thrown at modules/flowable-event-registry/src/main/java/org/flowable/eventregistry/impl/cmd/SetChannelDefinitionCategoryCmd.java:42

/**
 * @author Tijs Rademakers
 * @author Joram Barrez
 */
public class SetChannelDefinitionCategoryCmd implements Command<Void> {

    protected String channelDefinitionId;
    protected String category;

    public SetChannelDefinitionCategoryCmd(String channelDefinitionId, String category) {
        this.channelDefinitionId = channelDefinitionId;
        this.category = category;
    }

    @Override
    public Void execute(CommandContext commandContext) {

        if (channelDefinitionId == null) {
            throw new FlowableIllegalArgumentException("Channel definition id is null");
        }

        ChannelDefinitionEntity channelDefinition = CommandContextUtil.getChannelDefinitionEntityManager(commandContext).findById(channelDefinitionId);

        if (channelDefinition == null) {
            throw new FlowableObjectNotFoundException("No channel definition found for id = '" + channelDefinitionId + "'");
        }

        // Update category
        channelDefinition.setCategory(category);

        // Remove channel from cache, it will be refetch later
        DeploymentCache<ChannelDefinitionCacheEntry> channelDefinitionCache = CommandContextUtil.getEventRegistryConfiguration().getChannelDefinitionCache();
        if (channelDefinitionCache != null) {
            channelDefinitionCache.remove(channelDefinitionId);
        }

        CommandContextUtil.getChannelDefinitionEntityManager(commandContext).update(channelDefinition);

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Fetch the channel definition by key/name first to obtain its id, then pass that id.
2. Validate the id is non-null in your code before calling the command.
3. Correct the call site so the channel definition id (not key) is passed.

Example fix

// before
repositoryService.setChannelDefinitionCategory(null, "marketing");
// after
ChannelDefinition ch = eventRepositoryService.createChannelDefinitionQuery().channelDefinitionKey("myChannel").latestVersion().singleResult();
repositoryService.setChannelDefinitionCategory(ch.getId(), "marketing");

if (channelDefinitionId == null || channelDefinitionId.isBlank()) {
    throw new IllegalArgumentException("channelDefinitionId is required");
}

boolean hasChannelId(ChannelDefinition ch) {
    return ch != null && ch.getId() != null && !ch.getId().isBlank();
}

try {
    eventRepositoryService.setChannelDefinitionCategory(channelDefinitionId, category);
} catch (FlowableIllegalArgumentException e) {
    log.error("Channel definition id missing", e);
}

When it happens

Trigger: Calling the set-channel-definition-category API with a null id, e.g. a variable from a lookup that returned nothing, or a caller mixing up key vs id.

Common situations: Passing an event definition key where the API expects a channel definition id; a prior findById/getChannelDefinition call returning null and its result being forwarded; refactoring that renamed a field but not the argument.

Related errors

• channelDefinitionKey and channelDefinitionId are null
• event consumer is null.
• resourceName is null
• resourceNameLike is null
• form tenantId is null

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/e391fd9ab870fe9c. Report an issue: GitHub.