What causes "No channel definition found for key ''" in flowable/flowable-engine?

Deploy the channel model XML that defines this key and redeploy

flowable/flowable-engine · error · FlowableObjectNotFoundException

No channel definition found for key ''

Error message

No channel definition found for key ''

What it means

Thrown when resolving a channel definition by key with no tenant (tenantId null or NO_TENANT_ID) and no parent deployment, and no deployed latest definition exists for that key. FlowableObjectNotFoundException naming the key.

Solutions

Deploy the channel model XML that defines this key and redeploy
Check the key spelling (case-sensitive) against the deployed definitions: repositoryService.createChannelDefinitionQuery().list()
List deployments to confirm the channel was deployed to this engine/database

Example fix

// before
ChannelDefinition cd = channelModelLookup("inbound-custmr-event"); // typo, never matches
// after
ChannelDefinition cd = channelModelLookup("inbound-customer-event"); // key exactly as in XML <channel id="inbound-customer-event">

Defensive patterns

Strategy: try-catch

Validate before calling

if (repositoryService.createChannelDefinitionQuery()
        .channelDefinitionKey(key).latest().singleResult() == null) {
    deployChannelIfNeeded(key); // ensure the channel XML is deployed
}

Try / catch

try {
    return repositoryService.getChannelModel(null, key, null, null);
} catch (FlowableObjectNotFoundException e) {
    LOGGER.error("no channel deployed for key {}; deployments: {}", key,
        repositoryService.createDeploymentQuery().list());
    throw e;
}

Prevention

Deploy channel models at application startup before any lookups
Keep channel keys in constants shared between deployer and consumer code

When it happens

Trigger: Calling getChannelModel with channelDefinitionKey set (no id), where no channel definition with that key has been deployed, or the deployment containing it was deleted.

Common situations: Deploying the channel XML with a different key than the one the application looks up; forgetting to deploy before first use; deleting the deployment that contained the channel.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

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

        EventRegistryEngineConfiguration eventEngineConfiguration = CommandContextUtil.getEventRegistryConfiguration(commandContext);
        EventDeploymentManager deploymentManager = eventEngineConfiguration.getDeploymentManager();
        ChannelDefinitionEntityManager channelDefinitionEntityManager = eventEngineConfiguration.getChannelDefinitionEntityManager();

        // Find the channel definition
        ChannelDefinitionEntity channelDefinitionEntity = null;
        if (channelDefinitionId != null) {

            channelDefinitionEntity = deploymentManager.findDeployedChannelDefinitionById(channelDefinitionId);
            if (channelDefinitionEntity == null) {
                throw new FlowableObjectNotFoundException("No channel definition found for id = '" + channelDefinitionId + "'", ChannelDefinitionEntity.class);
            }

        } else if (channelDefinitionKey != null && (tenantId == null || EventRegistryEngineConfiguration.NO_TENANT_ID.equals(tenantId)) && 
                        (parentDeploymentId == null || eventEngineConfiguration.isAlwaysLookupLatestDefinitionVersion())) {

            channelDefinitionEntity = deploymentManager.findDeployedLatestChannelDefinitionByKey(channelDefinitionKey);
            if (channelDefinitionEntity == null) {
                throw new FlowableObjectNotFoundException("No channel definition found for key '" + channelDefinitionKey + "'", ChannelDefinitionEntity.class);
            }

        } else if (channelDefinitionKey != null && tenantId != null && !EventRegistryEngineConfiguration.NO_TENANT_ID.equals(tenantId) && 
                        (parentDeploymentId == null || eventEngineConfiguration.isAlwaysLookupLatestDefinitionVersion())) {

            channelDefinitionEntity = channelDefinitionEntityManager.findLatestChannelDefinitionByKeyAndTenantId(channelDefinitionKey, tenantId);
            
            if (channelDefinitionEntity == null && eventEngineConfiguration.isFallbackToDefaultTenant()) {
                String defaultTenant = eventEngineConfiguration.getDefaultTenantProvider().getDefaultTenant(tenantId, ScopeTypes.EVENT_REGISTRY, channelDefinitionKey);
                if (StringUtils.isNotEmpty(defaultTenant)) {
                    channelDefinitionEntity = channelDefinitionEntityManager.findLatestChannelDefinitionByKeyAndTenantId(channelDefinitionKey, defaultTenant);
                } else {
                    channelDefinitionEntity = channelDefinitionEntityManager.findLatestChannelDefinitionByKey(channelDefinitionKey);
                }
            }

            if (channelDefinitionEntity == null) {
                throw new FlowableObjectNotFoundException("No channel definition found for key '" + channelDefinitionKey + "' for tenant identifier " + tenantId, ChannelDefinitionEntity.class);

View on GitHub (pinned to d6d39ce1c6)