apache/dolphinscheduler · error · ServiceException

Failed to parse command parameter for workflow instance %s

Error message

Failed to parse command parameter for workflow instance %s

What it means

The workflow instance's command parameter JSON could not be converted back into typed objects during parameter pre-parsing (paramParsingPreparation) — the commandParam JSON is malformed, contains types that no longer match the current class definitions, or was stored by an older incompatible version. Downstream parameter substitution for the task cannot proceed, so the instance fails before task dispatch.

Source

Thrown at dolphinscheduler-service/src/main/java/org/apache/dolphinscheduler/service/expand/CuringParamsServiceImpl.java:168

     * @param parameters
     * @param workflowInstance
     * @param projectName
     * @param workflowDefinitionName
     * @return
     */
    @Override
    public Map<String, Property> paramParsingPreparation(@NonNull TaskInstance taskInstance,
                                                         @NonNull AbstractParameters parameters,
                                                         @NonNull WorkflowInstance workflowInstance,
                                                         String projectName,
                                                         String workflowDefinitionName) {
        Map<String, Property> prepareParamsMap = new HashMap<>();

        // If it is a complement, you need to pass in the task instance id
        // to locate the time of the process instance complement.
        ICommandParam commandParam = JSONUtils.parseObject(workflowInstance.getCommandParam(), ICommandParam.class);
        if (commandParam == null) {
            throw new ServiceException(String.format("Failed to parse command parameter for workflow instance %s",
                    workflowInstance.getId()));
        }
        String timeZone = commandParam.getTimeZone();

        // 1. Built-in parameters (lowest precedence)
        Map<String, String> builtInParams = parseBuiltInParamsMap(
                taskInstance, workflowInstance, timeZone, projectName, workflowDefinitionName);
        safePutAll(prepareParamsMap, ParameterUtils.getUserDefParamsMap(builtInParams));

        // 2. Project-level parameters
        Map<String, Property> projectParams = getProjectParameterMap(taskInstance.getProjectCode());
        safePutAll(prepareParamsMap, projectParams);

        // 3. Workflow global parameters
        Map<String, Property> globalParams = parseGlobalParamsMap(workflowInstance);
        safePutAll(prepareParamsMap, globalParams);

        // 4. Task-local parameters

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Inspect workflowInstance.getCommandParam() JSON for syntax errors or truncated content
2. Re-run the instance with fresh parameters instead of recovering an instance whose stored command params are corrupt
3. If caused by a version upgrade schema change, migrate/patch the stored commandParam values
4. Add a pre-check that JSONUtils/mapStruct parsing result is non-null before use

When it happens

Trigger: Thrown at dolphinscheduler-service/src/main/java/org/apache/dolphinscheduler/service/expand/CuringParamsServiceImpl.java:168 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/faea5e4f157ada0c. Report an issue: GitHub.