flowable/flowable-engine · error · FlowableException

Could not deserialize job configuration

Error message

Could not deserialize job configuration

What it means

The job handler deserializes its job configuration (transition and plan item instance reference) from the job entity before acting. Any exception thrown during that deserialization is wrapped in FlowableException('Could not deserialize job configuration'). It signals a corrupted or incompatible job configuration rather than a business-rule violation.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/job/AsyncLeaveActivePlanItemInstanceJobHandler.java:87

                    CommandContextUtil.getAgenda(commandContext).planTerminatePlanItemInstanceOperation(planItemInstanceEntity, exitType, exitEventType);

                } else if (PlanItemTransition.FAULT.equals(transition)) {
                    String errorCode = jsonConfiguration.path(OperationSerializationMetadata.FIELD_ERROR_CODE).stringValue(null);
                    if (errorCode != null) {
                        String errorMessage = jsonConfiguration.path(OperationSerializationMetadata.FIELD_ERROR_MESSAGE).stringValue(null);
                        CmmnFault reconstructedError = errorMessage != null ? new CmmnFault(errorCode, errorMessage) : new CmmnFault(errorCode);
                        CommandContextUtil.getAgenda(commandContext).planFailPlanItemInstanceOperation(planItemInstanceEntity, reconstructedError);
                    } else {
                        CommandContextUtil.getAgenda(commandContext).planFailPlanItemInstanceOperation(planItemInstanceEntity);
                    }

                } else {
                    throw new FlowableException("Programmatic error: unsupported transition " + transition + " for " + planItemInstanceEntity);

                }

            } catch (Exception e) {
                throw new FlowableException("Could not deserialize job configuration", e);
            }

        } else {
            throw new FlowableException("Invalid usage of " + TYPE + " job handler, variable scope is of type " + variableScope.getClass());
        }
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Dump the job row's CONFIG_ value and validate it against the expected format used by this handler version.
2. Delete the corrupted job row (or let the dead-letter/job-retry mechanism park it) after confirming the plan item state; recreate the operation via the CMMN runtime API if the transition is still needed.
3. Align engine versions: if jobs were persisted by a different Flowable version, migrate the database schema/data consistently before restarting the executor.
4. Check for DB-level truncation or encoding issues on the configuration column.

try {
    // job execution path
} catch (FlowableException e) {
    if ("Could not deserialize job configuration".equals(e.getMessage())) {
        log.error("Corrupted job config for job " + jobId + ", moving to dead letter", e);
        jobService.moveJobToDeadLetterJob(jobId);
    } else { throw e; }
}

When it happens

Trigger: execute() calls the JSON/serialization utility to read the job's configuration string and the parse/convert step throws (malformed JSON, wrong structure, missing keys, incompatible class shape after upgrade).

Common situations: Job rows edited manually in ACT_RU_JOB; configuration written by a newer/older Flowable version than the one executing; database migration truncating the CONFIG_ column; custom serializers producing a different payload shape.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

• Invalid usage of ${TYPE} job handler, case instance ${caseIn
• Programmatic error: unsupported transition ${transition} for
• Invalid usage of ${TYPE} job handler, variable scope is of t
• Error reading app resource
• Setting variable is not supported for read only delegate exe

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