flowable/flowable-engine · error · FlowableException

Error parsing channel definition JSON

Error message

Error parsing channel definition JSON

What it means

ChannelDefinitionParse.execute() reads the channel definition JSON from its StreamSource, parses it into a ChannelModel, and populates channel definition entities. Any exception in this pipeline — unreadable stream, malformed JSON, mapping errors — is wrapped in a FlowableException with this generic message, keeping the original cause attached.

Source

Thrown at modules/flowable-event-registry/src/main/java/org/flowable/eventregistry/impl/parser/ChannelDefinitionParse.java:90

        try (InputStreamReader in = newInputStreamReaderForSource(encoding)) {
            String channelJson = IOUtils.toString(in);
            channelModel = converter.convertToChannelModel(channelJson);

            if (channelModel != null && channelModel.getKey() != null) {
                ChannelDefinitionEntity channelDefinitionEntity = eventEngineConfig.getChannelDefinitionEntityManager().create();
                channelDefinitionEntity.setCreateTime(new Date());
                channelDefinitionEntity.setKey(channelModel.getKey());
                channelDefinitionEntity.setCategory(channelModel.getCategory());
                channelDefinitionEntity.setName(channelModel.getName());
                channelDefinitionEntity.setDescription(channelModel.getDescription());
                channelDefinitionEntity.setType(channelModel.getChannelType());
                channelDefinitionEntity.setImplementation(channelModel.getType());
                channelDefinitionEntity.setResourceName(name);
                channelDefinitionEntity.setDeploymentId(deployment.getId());
                channelDefinitions.add(channelDefinitionEntity);
            }
        } catch (Exception e) {
            throw new FlowableException("Error parsing channel definition JSON", e);
        }
        return this;
    }

    private InputStreamReader newInputStreamReaderForSource(String encoding) throws UnsupportedEncodingException {
        if (encoding != null) {
            return new InputStreamReader(streamSource.getInputStream(), encoding);
        } else {
            return new InputStreamReader(streamSource.getInputStream());
        }
    }

    public ChannelDefinitionParse name(String name) {
        this.name = name;
        return this;
    }

    public ChannelDefinitionParse sourceInputStream(InputStream inputStream) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Validate the channel JSON with a JSON linter / JSON schema before deploying
2. Inspect the cause chain (getCause) to find whether it's an IO error or a JSON parse error
3. Confirm the file content type — it must be channel definition JSON matching the Flowable ChannelModel schema
4. Re-export a known-good channel definition from a working project and compare structure

Example fix

// before: channels/myChannel.channel
{"key": 'myChannel', type: jms}   // invalid JSON: single quotes, unquoted value
// after
{"key": "myChannel", "type": "jms"}

try (Reader r = new InputStreamReader(new FileInputStream(channelFile), StandardCharsets.UTF_8)) {
    new JsonParser().parse(r); // throws if invalid JSON
}

try {
    parse.execute();
} catch (FlowableException e) {
    if (e.getMessage().equals("Error parsing channel definition JSON")) {
        log.error("Channel JSON invalid", e.getCause());
    }
}

When it happens

Trigger: Executing a channel definition parse during deployment when the resource content is invalid JSON, the stream cannot be read, or the JSON does not match the expected ChannelModel structure.

Common situations: Hand-edited .channel JSON files with syntax errors (trailing commas, unquoted keys); wrong file deployed (HTML error page or YAML saved as .channel); encoding mismatches producing garbage bytes; schema changes after a Flowable upgrade.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Related errors

• Error parsing event definition JSON
• No channel keys configured for ${execution}
• deployment '${deploymentId}' didn't put channel definition '
• Unsupported event payload instance type: ${definitionType}
• Could not serialize event to json string for ${eventInstance

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