{"record":{"id":"cbe618e9ad6d920d","repo":"apache/dolphinscheduler","slug":"recover-workflow-instance-failed-s-cbe618","errorCode":null,"errorMessage":"Recover workflow instance failed: %s","messagePattern":"Recover workflow instance failed: (.+?)","errorType":"exception","errorClass":"ServiceException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/executor/workflow/RecoverSuspendedWorkflowInstanceExecutorDelegate.java","lineNumber":65,"sourceCode":"                    String.format(\"The workflow instance: %s state is %s, cannot recovery\", workflowInstance.getName(),\n                            workflowInstance.getState()));\n        }\n        final Server masterServer = registryClient.getRandomServer(RegistryNodeType.MASTER).orElse(null);\n        if (masterServer == null) {\n            throw new ServiceException(\"no master server available\");\n        }\n        final WorkflowInstanceRecoverSuspendTasksRequest recoverSuspendTaskRequest =\n                WorkflowInstanceRecoverSuspendTasksRequest.builder()\n                        .workflowInstanceId(workflowInstance.getId())\n                        .userId(workflowInstanceControlRequest.executeUser.getId())\n                        .build();\n\n        final WorkflowInstanceRecoverSuspendTasksResponse recoverSuspendTaskResponse = Clients\n                .withService(IWorkflowControlClient.class)\n                .withHost(masterServer.getHost() + \":\" + masterServer.getPort())\n                .triggerFromSuspendTasks(recoverSuspendTaskRequest);\n        if (!recoverSuspendTaskResponse.isSuccess()) {\n            throw new ServiceException(\"Recover workflow instance failed: \" + recoverSuspendTaskResponse.getMessage());\n        }\n        return null;\n    }\n\n    public static class RecoverSuspendedWorkflowInstanceOperation {\n\n        private final RecoverSuspendedWorkflowInstanceExecutorDelegate recoverSuspendedWorkflowInstanceExecutorDelegate;\n\n        private WorkflowInstance workflowInstance;\n\n        private User executeUser;\n\n        public RecoverSuspendedWorkflowInstanceOperation(RecoverSuspendedWorkflowInstanceExecutorDelegate recoverSuspendedWorkflowInstanceExecutorDelegate) {\n            this.recoverSuspendedWorkflowInstanceExecutorDelegate = recoverSuspendedWorkflowInstanceExecutorDelegate;\n        }\n\n        public RecoverSuspendedWorkflowInstanceExecutorDelegate.RecoverSuspendedWorkflowInstanceOperation onWorkflowInstance(WorkflowInstance workflowInstance) {\n            this.workflowInstance = workflowInstance;","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/executor/workflow/RecoverSuspendedWorkflowInstanceExecutorDelegate.java#L47-L83","documentation":"Thrown by RecoverSuspendedWorkflowInstanceExecutorDelegate.execute when the master server's IWorkflowControlClient responds to a triggerFromSuspendTasks request with a non-success response. The API module asked the master to resume a suspended workflow instance from its suspended tasks, and the master reported failure; the master's message is appended. It indicates the resume operation was rejected or failed server-side.","triggerScenarios":"Calling recover on a suspended workflow instance where the master's triggerFromSuspendTasks returns success=false, e.g. the workflow instance was deleted or modified between request and execution, the suspended task no longer exists, or the master rejects the recover due to invalid instance state.","commonSituations":"Recovering a workflow instance that another user already stopped or recovered; racing with master failover so the instance's host changed; stale UI data pointing at an old suspended instance; master-side command generation errors.","solutions":["Read the appended recoverSuspendTaskResponse.getMessage() for the master-side cause and fix that underlying issue","Refresh the workflow instance list and verify the instance is still in a suspended state before recovering","Retry the recover operation; transient master issues can cause failures","Check master server logs around the request time for the root failure","Verify the master server the API contacted is healthy and holds the instance"],"exampleFix":"// before\nClients.withService(IWorkflowControlClient.class)\n    .withHost(masterServer.getHost() + \":\" + masterServer.getPort())\n    .triggerFromSuspendTasks(recoverSuspendTaskRequest);\n// after\n// check state client-side before triggering\nif (!workflowInstance.getState().isSuspend()) {\n    throw new ServiceException(\"Instance is not suspended, cannot recover\");\n}","handlingStrategy":"try-catch","validationCode":"WorkflowInstance wi = getFreshInstance(id);\nif (wi == null || wi.getState() == null || !wi.getState().isSuspend()) {\n    throw new IllegalArgumentException(\"Instance not in suspended state\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    recoverExecutorDelegate.execute(op);\n} catch (ServiceException e) {\n    log.error(\"Recover failed: {}\", e.getMessage(), e);\n    // refresh instance state and surface master-side message to user\n}","preventionTips":["Refresh instance state immediately before recovering","Verify the instance is suspended and its host master is alive","Surface the master's response message to the operator","Check master availability before issuing recover"],"tags":["workflow","master-server","rpc-response"],"backgroundTag":"api-error-response","analyzedSha":"02eac45a1b6676e639fcbfb4be2243de5771b05d","analyzedAt":"2026-09-06T17:43:00.555Z","contentChangedAt":"2026-09-06T17:43:00.555Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}