{"record":{"id":"e6c259c001efe6e4","repo":"apache/dolphinscheduler","slug":"the-workflowfailovercommandparam-commandparam","errorCode":null,"errorMessage":"The WorkflowFailoverCommandParam: ${commandParam} is invalid","messagePattern":"The WorkflowFailoverCommandParam: (.+?) is invalid","errorType":"exception","errorClass":"java.lang.IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-master/src/main/java/org/apache/dolphinscheduler/server/master/engine/command/handler/WorkflowFailoverCommandHandler.java","lineNumber":86,"sourceCode":"     *     <li>command type</li>\n     *     <li>start time</li>\n     *     <li>restart time</li>\n     *     <li>end time</li>\n     *     <li>run times</li>\n     * </ul>\n     */\n    @Override\n    protected void assembleWorkflowInstance(\n                                            final WorkflowExecuteContextBuilder workflowExecuteContextBuilder) {\n        final Command command = workflowExecuteContextBuilder.getCommand();\n        final int workflowInstanceId = command.getWorkflowInstanceId();\n        final WorkflowInstance workflowInstance = workflowInstanceDao.queryOptionalById(workflowInstanceId)\n                .orElseThrow(() -> new IllegalArgumentException(\"Cannot find WorkflowInstance:\" + workflowInstanceId));\n        final WorkflowFailoverCommandParam workflowFailoverCommandParam = JSONUtils.parseObject(\n                command.getCommandParam(),\n                WorkflowFailoverCommandParam.class);\n        if (workflowFailoverCommandParam == null) {\n            throw new IllegalArgumentException(\n                    \"The WorkflowFailoverCommandParam: \" + command.getCommandParam() + \" is invalid\");\n        }\n        workflowInstance.setRestartTime(new Date());\n        workflowInstance.setState(workflowFailoverCommandParam.getWorkflowExecutionStatus());\n        workflowInstance.setHost(masterConfig.getMasterAddress());\n        workflowInstanceDao.updateById(workflowInstance);\n\n        workflowExecuteContextBuilder.setWorkflowInstance(workflowInstance);\n    }\n\n    /**\n     * Generate the workflow execution graph.\n     * <p> Will rebuild the WorkflowExecutionGraph from the exist task instance.\n     */\n    @Override\n    protected void assembleWorkflowExecutionGraph(final WorkflowExecuteContextBuilder workflowExecuteContextBuilder) {\n        final Map<String, TaskInstance> taskInstanceMap =\n                getValidTaskInstance(workflowExecuteContextBuilder.getWorkflowInstance())","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-master/src/main/java/org/apache/dolphinscheduler/server/master/engine/command/handler/WorkflowFailoverCommandHandler.java#L68-L104","documentation":"WorkflowFailoverCommandHandler.assembleWorkflowInstance parses the failover command's commandParam JSON into WorkflowFailoverCommandParam; if JSONUtils.parseObject returns null (empty, malformed, or non-matching JSON), this IllegalArgumentException is thrown because failover cannot proceed without the execution status carried in the param.","triggerScenarios":"A WorkflowFailoverCommand whose commandParam is null, empty string, invalid JSON, or valid JSON lacking the fields needed to deserialize into WorkflowFailoverCommandParam.","commonSituations":"Commands produced by older versions with a different param schema, manual DB inserts into t_ds_command with wrong command_param, or corruption of the command table.","solutions":["Inspect the t_ds_command row for the failing command and verify command_param is valid JSON like {\"workflowInstanceId\":..., \"workflowExecutionStatus\":...}","Delete or fix the malformed failover command row so master stops retrying it","Re-trigger failover through the supported failover path instead of crafting commands manually"],"exampleFix":"// before (bad command_param)\n{\"instanceId\": 123}\n// after\n{\"workflowInstanceId\": 123, \"workflowExecutionStatus\": \"RUNNING_EXECUTION\"}","handlingStrategy":"validation","validationCode":"String param = command.getCommandParam();\nif (param == null || param.isEmpty() || JSONUtils.parseObject(param, WorkflowFailoverCommandParam.class) == null) {\n    // reject before processing\n}","typeGuard":"boolean isValidFailoverParam(String json) {\n    return json != null && JSONUtils.parseObject(json, WorkflowFailoverCommandParam.class) != null;\n}","tryCatchPattern":"try {\n    handler.handleCommand(command);\n} catch (IllegalArgumentException e) {\n    log.error(\"Dropping invalid failover command: {}\", e.getMessage());\n    commandDao.deleteCommand(command.getId()); // avoid infinite retry\n}","preventionTips":["Never insert rows into t_ds_command manually without correct command_param JSON","After upgrades, purge legacy-format commands from t_ds_command","Wrap command creation in a helper that serializes WorkflowFailoverCommandParam via JSONUtils"],"tags":["json","failover","master-server"],"backgroundTag":"json-unmarshal-failed","analyzedSha":"02eac45a1b6676e639fcbfb4be2243de5771b05d","analyzedAt":"2026-09-06T17:43:00.555Z","contentChangedAt":"2026-09-06T17:43:00.555Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}