{"record":{"id":"200d09895d4aa86b","repo":"apache/dolphinscheduler","slug":"the-releasestate-releasestate-is-illegal-please","errorCode":null,"errorMessage":"The releaseState {releaseState} is illegal, please check it.","messagePattern":"The releaseState (.+?) is illegal, please check it\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/controller/WorkflowDefinitionController.java","lineNumber":364,"sourceCode":"            @Parameter(name = \"releaseState\", description = \"WORKFLOW_DEFINITION_RELEASE\", required = true, schema = @Schema(implementation = ReleaseState.class)),\n    })\n    @PostMapping(value = \"/{code}/release\")\n    @ResponseStatus(HttpStatus.OK)\n    @ApiException(RELEASE_WORKFLOW_DEFINITION_ERROR)\n    @OperatorLog(auditType = AuditType.WORKFLOW_RELEASE)\n    public Result<Boolean> releaseWorkflowDefinition(@Parameter(hidden = true) @RequestAttribute(value = Constants.SESSION_USER) User loginUser,\n                                                     @Parameter(name = \"projectCode\", description = \"PROJECT_CODE\", required = true) @PathVariable long projectCode,\n                                                     @PathVariable(value = \"code\", required = true) long workflowDefinitionCode,\n                                                     @RequestParam(value = \"releaseState\", required = true) ReleaseState releaseState) {\n        switch (releaseState) {\n            case ONLINE:\n                workflowDefinitionService.onlineWorkflowDefinition(loginUser, projectCode, workflowDefinitionCode);\n                break;\n            case OFFLINE:\n                workflowDefinitionService.offlineWorkflowDefinition(loginUser, projectCode, workflowDefinitionCode);\n                break;\n            default:\n                throw new IllegalArgumentException(\n                        \"The releaseState \" + releaseState + \" is illegal, please check it.\");\n        }\n        return Result.success(true);\n    }\n\n    /**\n     * query detail of workflow definition by code\n     *\n     * @param loginUser   login user\n     * @param projectCode project code\n     * @param code        workflow definition code\n     * @return workflow definition detail\n     */\n    @Operation(summary = \"queryWorkflowDefinitionByCode\", description = \"QUERY_WORKFLOW_DEFINITION_BY_CODE_NOTES\")\n    @Parameters({\n            @Parameter(name = \"code\", description = \"WORKFLOW_DEFINITION_CODE\", required = true, schema = @Schema(implementation = long.class, example = \"123456789\"))\n    })\n    @GetMapping(value = \"/{code}\")","sourceCodeStart":346,"sourceCodeEnd":382,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/controller/WorkflowDefinitionController.java#L346-L382","documentation":"WorkflowDefinitionController.releaseWorkflowDefinition switches on the releaseState parameter (ONLINE/OFFLINE). Any other value reaches the default branch and throws IllegalArgumentException 'The releaseState X is illegal, please check it.' Unlike the ServiceException paths, this is an unhandled Java runtime exception, typically surfacing as a 500.","triggerScenarios":"POST /projects/{code}/workflow-definition/{wfCode}/release with releaseState not equal to ONLINE or OFFLINE (e.g. 'online' lowercase, 'ENABLE', or an empty value).","commonSituations":"Scripts using 'ONLINE'/'OFFLINE' synonyms like 'PUBLISH'/'UNPUBLISH'; case or whitespace mistakes; older API clients using a state name removed in a version upgrade.","solutions":["Send releaseState as exactly ONLINE or OFFLINE (uppercase enum name).","Trim and uppercase the state client-side before calling the endpoint.","For custom tooling, validate against ReleaseState.valueOf() first so failures are caught before the HTTP call."],"exampleFix":"// before\nparams.put(\"releaseState\", \"online\");\n// after\nparams.put(\"releaseState\", ReleaseState.ONLINE.name());","handlingStrategy":"validation","validationCode":"ReleaseState state;\ntry {\n    state = ReleaseState.valueOf(releaseState.trim().toUpperCase());\n} catch (IllegalArgumentException e) {\n    throw new IllegalArgumentException(\"releaseState must be ONLINE or OFFLINE\");\n}\nif (state != ReleaseState.ONLINE && state != ReleaseState.OFFLINE) {\n    throw new IllegalArgumentException(\"releaseState must be ONLINE or OFFLINE\");\n}","typeGuard":"boolean isValidReleaseState(String s) {\n    return \"ONLINE\".equals(s) || \"OFFLINE\".equals(s);\n}","tryCatchPattern":"try {\n    controller.releaseWorkflowDefinition(loginUser, projectCode, code, releaseState);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().startsWith(\"The releaseState\")) {\n        log.error(\"Use exactly ONLINE or OFFLINE: {}\", e.getMessage());\n    }\n}","preventionTips":["Always send the uppercase enum names ONLINE/OFFLINE.","Normalize releaseState (trim/uppercase) in automation scripts.","Since this throws a raw IllegalArgumentException, catch RuntimeException on this endpoint, not just ServiceException."],"tags":["rest-api","enum","invalid-enum-value","workflow-definition"],"backgroundTag":"invalid-enum-value","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"}