flowable/flowable-engine · error · FlowableEventJsonException

A channel key detection value is required for the channel mo

Error message

A channel key detection value is required for the channel model with key ${key}

What it means

Thrown by Flowable's inbound channel JSON converter when a channel model declares the 'json' deserializer type but has no ChannelEventKeyDetection configured. Key detection tells the event registry how to extract the event key from the JSON payload so it can match the payload to a registered event definition. Without it, the registry cannot classify incoming JSON payloads.

Source

Thrown at modules/flowable-event-registry-json-converter/src/main/java/org/flowable/eventregistry/json/converter/InboundChannelModelValidator.java:45

        if (channelModel instanceof InboundChannelModel inboundChannelModel) {

            validateChannel(inboundChannelModel);
        }
    }

    protected void validateChannel(InboundChannelModel inboundChannelModel) {
        if (StringUtils.isEmpty(inboundChannelModel.getPipelineDelegateExpression())) {
            // Deserializer is only needed if there is no pipeline delegate expression
            validateDeserializer(inboundChannelModel);
        }
    }

    protected void validateDeserializer(InboundChannelModel inboundChannelModel) {
        String deserializerType = inboundChannelModel.getDeserializerType();
        ChannelEventKeyDetection channelEventKeyDetection = inboundChannelModel.getChannelEventKeyDetection();
        if ("json".equalsIgnoreCase(deserializerType)) {
            if (channelEventKeyDetection == null) {
                throw new FlowableEventJsonException("A channel key detection value is required for the channel model with key " + inboundChannelModel.getKey());
            }

            if (StringUtils.isEmpty(channelEventKeyDetection.getFixedValue()) &&
                StringUtils.isEmpty(channelEventKeyDetection.getJsonField()) &&
                StringUtils.isEmpty(channelEventKeyDetection.getJsonPointerExpression()) &&
                StringUtils.isEmpty(channelEventKeyDetection.getDelegateExpression())) {
                throw new FlowableEventJsonException(
                    "The channel json key detection value was not found for the channel model with key " + inboundChannelModel.getKey()
                        + ". One of fixedValue, jsonField, jsonPointerExpression, delegateExpression should be set.");
            }

        } else if ("xml".equalsIgnoreCase(deserializerType)) {
            if (channelEventKeyDetection == null) {
                throw new FlowableEventJsonException("A channel key detection value is required for the channel model with key " + inboundChannelModel.getKey());
            }

            if (StringUtils.isEmpty(channelEventKeyDetection.getFixedValue()) &&
                StringUtils.isEmpty(channelEventKeyDetection.getXmlXPathExpression()) &&

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Add a channelEventKeyDetection section to the channel model JSON with one of fixedValue, jsonField, jsonPointerExpression, or delegateExpression
2. If the event key is known up front, set channelEventKeyDetection.fixedValue to the event definition key
3. Use channelEventKeyDetection.jsonField or jsonPointerExpression when the key is embedded in the payload
4. Provide channelEventKeyDetection.delegateExpression pointing at a bean implementing ChannelEventKeyDetection for custom logic

Example fix

// before
{
  "key": "myChannel",
  "deserializerType": "json"
}
// after
{
  "key": "myChannel",
  "deserializerType": "json",
  "channelEventKeyDetection": {
    "jsonField": "type"
  }
}

if ("json".equalsIgnoreCase(channel.getDeserializerType()) && channel.getChannelEventKeyDetection() == null) {
    throw new IllegalArgumentException("channel '" + channel.getKey() + "' with json deserializer needs channelEventKeyDetection");
}

boolean hasKeyDetection = c -> c.getChannelEventKeyDetection() != null;

try {
    repositoryService.createEventRegistryChannelModelConverter().convertToChannelModel(json);
} catch (FlowableEventJsonException e) {
    logger.error("Channel model missing key detection: {}", e.getMessage());
}

When it happens

Trigger: Calling validateChannel/validateDeserializer on an InboundChannelModel whose deserializerType is 'json' and whose getChannelEventKeyDetection() returns null, e.g. an inbound channel JSON definition that omits the channelEventKeyDetection section.

Common situations: Hand-writing channel model JSON and forgetting the key detection block; converting channels from a fixed-key to a JSON-payload model without adding key detection; automated channel generation tools omitting the field.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• No channel keys configured for ${execution}
• EventRegistryEventDefinition on '" + elementId + "' has an e
• There is no correlation parameter with name '{correlationPar
• The channel json key detection value was not found for the c
• The channel xml key detection value was not found for the ch

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