What causes "No channel definition found for id = '${channelDefinitionId}'" in flowable/flowable-engine?

Query the current channel definition by key to get the valid id (createChannelDefinitionQuery().channelDefinitionKey(...).singleResult()).

flowable/flowable-engine · error · FlowableObjectNotFoundException

No channel definition found for id =

Error message

No channel definition found for id = '${channelDefinitionId}'

What it means

SetChannelDefinitionCategoryCmd.execute() looks up the channel definition by id; if findById returns null it throws FlowableObjectNotFoundException, meaning no channel definition with that id exists in the event registry.

Solutions

Query the current channel definition by key to get the valid id (createChannelDefinitionQuery().channelDefinitionKey(...).singleResult()).
Check you are connected to the expected database/engine where the channel definition exists.
Redeploy the event registry model containing the channel definition if it was deleted.
Verify the id value for truncation/encoding issues when sourced from external config.

Example fix

// before
repositoryService.setChannelDefinitionCategory("chan-123", "marketing"); // chan-123 not in DB
// after
ChannelDefinition ch = eventRepositoryService.createChannelDefinitionQuery().channelDefinitionKey("myChannel").latestVersion().singleResult();
repositoryService.setChannelDefinitionCategory(ch.getId(), "marketing");

Defensive patterns

Strategy: try-catch

Validate before calling

ChannelDefinition ch = eventRepositoryService.createChannelDefinitionQuery().channelDefinitionId(id).singleResult();
if (ch == null) throw new IllegalStateException("No channel definition with id " + id);

Type guard

boolean channelExists(String id) {
    return eventRepositoryService.createChannelDefinitionQuery().channelDefinitionId(id).count() > 0;
}

Try / catch

try {
    eventRepositoryService.setChannelDefinitionCategory(id, category);
} catch (FlowableObjectNotFoundException e) {
    log.warn("Channel definition {} no longer exists; re-resolving by key", id, e);
}

Prevention

Look up fresh ids by channel key instead of persisting ids across environments.
Re-resolve ids after any deployment cleanup job runs.
Confirm engine/database targeting before mutating definitions.

When it happens

Trigger: Calling setChannelDefinitionCategory with an id that was never created, that was deleted by a redeployment cleanup, or that belongs to a different database/engine instance.

Common situations: Hardcoded ids from another environment (dev vs prod databases); referencing a channel definition removed by cascade delete of a deployment; stale ids cached in application config after DB re-init.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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

Appendix: source

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

    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);

        return null;
    }

}

View on GitHub (pinned to d6d39ce1c6)