flowable/flowable-engine · error · IllegalStateException

Provided decision definition must have both key and resource

Error message

Provided decision definition must have both key and resource name set.

What it means

DecisionRequirementsDiagramHelper.createDiagramForDecision requires the DecisionEntity to carry both a key and a resource name before it can generate a diagram resource; otherwise it throws IllegalStateException. This is an internal precondition: the caller (per shouldCreateDiagram) must ensure a valid decision definition.

Source

Thrown at modules/flowable-dmn-engine/src/main/java/org/flowable/dmn/engine/impl/deployer/DecisionRequirementsDiagramHelper.java:42

import org.slf4j.LoggerFactory;

/**
 * Creates diagrams from decision definitions.
 */
public class DecisionRequirementsDiagramHelper {

    private static final Logger LOGGER = LoggerFactory.getLogger(DecisionRequirementsDiagramHelper.class);

    /**
     * Generates a diagram resource for a DecisionEntity. The returned resource has not yet been persisted, nor attached to the CaseDefinitionEntity. This requires
     * that the DecisionEntity have its key and resource name already set.
     * <p>
     * The caller must determine whether creating a diagram for this decision is appropriate or not, for example see {@link #shouldCreateDiagram}.
     */
    public DmnResourceEntity createDiagramForDecision(DecisionEntity decision, DmnDefinition dmnDefinition) {

        if (StringUtils.isEmpty(decision.getKey()) || StringUtils.isEmpty(decision.getResourceName())) {
            throw new IllegalStateException("Provided decision definition must have both key and resource name set.");
        }

        DmnResourceEntity resource = createResourceEntity();
        DmnEngineConfiguration dmnEngineConfiguration = CommandContextUtil.getDmnEngineConfiguration();
        try {
            byte[] diagramBytes = IoUtil.readInputStream(
                    dmnEngineConfiguration.getDecisionRequirementsDiagramGenerator().generateDiagram(dmnDefinition, "png",
                            dmnEngineConfiguration.getDecisionFontName(),
                            dmnEngineConfiguration.getLabelFontName(),
                            dmnEngineConfiguration.getAnnotationFontName(),
                            dmnEngineConfiguration.getClassLoader()), null);
            String diagramResourceName = ResourceNameUtil.getDecisionRequirementsDiagramResourceName(
                    decision.getResourceName(), decision.getKey(), "png");

            resource.setName(diagramResourceName);
            resource.setBytes(diagramBytes);
            resource.setDeploymentId(decision.getDeploymentId());

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Fix the DMN XML so each <decision id="..."> has a non-empty id and is referenced from a valid resource.
2. In custom parsing/deployer code, set both key and resourceName on the DecisionEntity before diagram generation.
3. Validate DMN files with the XSD before deploying.
4. Check shouldCreateDiagram is honored so diagram creation only runs for complete decisions.

Example fix

// before (custom parse handler)
DecisionEntity decision = new DecisionEntityImpl();
// key/resourceName never set
// after
DecisionEntity decision = new DecisionEntityImpl();
decision.setKey(decisionElement.getAttribute("id"));
decision.setResourceName(resource.getName());

if (StringUtils.isEmpty(decision.getKey()) || StringUtils.isEmpty(decision.getResourceName())) {
    throw new IllegalStateException("Decision must have key and resourceName before diagram generation");
}

try {
    return helper.createDiagramForDecision(decision, dmnDefinition);
} catch (IllegalStateException e) {
    log.warn("Skipping diagram for incomplete decision {}: {}", decision.getKey(), e.getMessage());
    return null;
}

When it happens

Trigger: Deploying DMN where a parsed DecisionEntity ends up with an empty key or resourceName — typically a malformed DMN XML whose decision element lacks an id, or custom deployer/parsing code that builds decisions without setting those fields.

Common situations: Hand-edited or generated .dmn XML with missing decision id attribute; custom DmnParseHandlers that skip setting resourceName; version upgrades where decision entity population changed.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Provided decision definition must have its resource name set
• Cannot find case definition for id:
• DMN repository service is not available
• Dmn engine is not configured
• key is null

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