flowable/flowable-engine · error · FlowableException

Error parsing Process Instance Migration Document

Error message

Error parsing Process Instance Migration Document

What it means

Wrapping error thrown when the Jackson ObjectMapper fails to parse a JSON document while deserializing a Process Instance Migration Document (convertFromJson). The original JacksonException is attached as the cause.

Solutions

1. Validate the migration JSON with a JSON linter/parser before calling convertFromJson.
2. Inspect the cause (JacksonException) message for exact line/character of the syntax error.
3. Regenerate the document using ProcessInstanceMigrationBuilder and migrateProcessInstances() serialization instead of hand-writing JSON.
4. Ensure the input is read fully and as UTF-8 without BOM.

Example fix

// before
String bad = "{ \"migrations\": [ }"; // malformed
document = ProcessInstanceMigrationDocumentConverter.convert(bad);

// after
String good = "{ \"migrations\": [] }"; // validated JSON
ObjectNode node = (ObjectNode) new ObjectMapper().readTree(good); // pre-validate
document = ProcessInstanceMigrationDocumentConverter.convert(node);

try (Parser p = new JsonParser()) { p.parse(json); } // or objectMapper.readTree(json) as pre-check

try {
    doc = ProcessInstanceMigrationDocumentConverter.convert(json);
} catch (FlowableException e) {
    logger.error("Invalid migration document JSON", e.getCause());
    throw new IllegalArgumentException("Malformed migration document", e);
}

When it happens

Trigger: Calling ProcessInstanceMigrationDocumentConverter.convertFromJson with a malformed JSON string/stream, wrong content type, or truncated JSON — Jackson throws JacksonException during parsing of any node in the migration document.

Common situations: Hand-edited migration JSON with syntax errors; file saved with BOM or wrong encoding; passing a non-JSON payload (e.g. XML or empty string) to the converter; response from an HTTP API cut off.

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 Case Instance Migration Document
• Error parsing Historic Case Instance Migration Document
• Error parsing channel definition JSON
• Error parsing event definition JSON
• Error reading channel json

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/migration/ProcessInstanceMigrationDocumentConverter.java:268

                for (JsonNode mappingNode : enableActivityMappings) {
                    if (mappingNode.hasNonNull(ProcessInstanceMigrationDocumentConstants.ACTIVITY_ID_JSON_PROPERTY)) {
                        EnableActivityMapping.EnableMapping enableMapping = new EnableActivityMapping.EnableMapping(
                                mappingNode.get(ProcessInstanceMigrationDocumentConstants.ACTIVITY_ID_JSON_PROPERTY).asString());
                        documentBuilder.addEnableActivityMapping(enableMapping);
                    }
                }
            }

            JsonNode processInstanceVariablesNode = rootNode.get(ProcessInstanceMigrationDocumentConstants.PROCESS_INSTANCE_VARIABLES_JSON_SECTION);
            if (processInstanceVariablesNode != null) {
                Map<String, Object> processInstanceVariables = ProcessInstanceMigrationDocumentConverter.convertFromJsonNodeToObject(processInstanceVariablesNode, objectMapper);
                documentBuilder.addProcessInstanceVariables(processInstanceVariables);
            }
            return documentBuilder.build();

        } catch (JacksonException e) {
            throw new FlowableException("Error parsing Process Instance Migration Document", e);
        }

    }

    protected static JsonNode convertToJsonProcessInstanceVariables(ProcessInstanceMigrationDocument processInstanceMigrationDocument, ObjectMapper objectMapper) {
        Map<String, Object> processInstanceVariables = processInstanceMigrationDocument.getProcessInstanceVariables();
        if (processInstanceVariables != null && !processInstanceVariables.isEmpty()) {
            return objectMapper.valueToTree(processInstanceVariables);
        }
        return null;
    }

    protected static JsonNode convertToJsonUpgradeScript(Script script, ObjectMapper objectMapper) {
        if (script != null) {
            return objectMapper.valueToTree(script);
        }
        return null;
    }

View on GitHub (pinned to d6d39ce1c6)