apache/dolphinscheduler · error · IllegalArgumentException

The releaseState {releaseState} is illegal, please check it.

Error message

The releaseState {releaseState} is illegal, please check it.

What it means

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.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/controller/WorkflowDefinitionController.java:364

            @Parameter(name = "releaseState", description = "WORKFLOW_DEFINITION_RELEASE", required = true, schema = @Schema(implementation = ReleaseState.class)),
    })
    @PostMapping(value = "/{code}/release")
    @ResponseStatus(HttpStatus.OK)
    @ApiException(RELEASE_WORKFLOW_DEFINITION_ERROR)
    @OperatorLog(auditType = AuditType.WORKFLOW_RELEASE)
    public Result<Boolean> releaseWorkflowDefinition(@Parameter(hidden = true) @RequestAttribute(value = Constants.SESSION_USER) User loginUser,
                                                     @Parameter(name = "projectCode", description = "PROJECT_CODE", required = true) @PathVariable long projectCode,
                                                     @PathVariable(value = "code", required = true) long workflowDefinitionCode,
                                                     @RequestParam(value = "releaseState", required = true) ReleaseState releaseState) {
        switch (releaseState) {
            case ONLINE:
                workflowDefinitionService.onlineWorkflowDefinition(loginUser, projectCode, workflowDefinitionCode);
                break;
            case OFFLINE:
                workflowDefinitionService.offlineWorkflowDefinition(loginUser, projectCode, workflowDefinitionCode);
                break;
            default:
                throw new IllegalArgumentException(
                        "The releaseState " + releaseState + " is illegal, please check it.");
        }
        return Result.success(true);
    }

    /**
     * query detail of workflow definition by code
     *
     * @param loginUser   login user
     * @param projectCode project code
     * @param code        workflow definition code
     * @return workflow definition detail
     */
    @Operation(summary = "queryWorkflowDefinitionByCode", description = "QUERY_WORKFLOW_DEFINITION_BY_CODE_NOTES")
    @Parameters({
            @Parameter(name = "code", description = "WORKFLOW_DEFINITION_CODE", required = true, schema = @Schema(implementation = long.class, example = "123456789"))
    })
    @GetMapping(value = "/{code}")

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Send releaseState as exactly ONLINE or OFFLINE (uppercase enum name).
2. Trim and uppercase the state client-side before calling the endpoint.
3. For custom tooling, validate against ReleaseState.valueOf() first so failures are caught before the HTTP call.

Example fix

// before
params.put("releaseState", "online");
// after
params.put("releaseState", ReleaseState.ONLINE.name());

ReleaseState state;
try {
    state = ReleaseState.valueOf(releaseState.trim().toUpperCase());
} catch (IllegalArgumentException e) {
    throw new IllegalArgumentException("releaseState must be ONLINE or OFFLINE");
}
if (state != ReleaseState.ONLINE && state != ReleaseState.OFFLINE) {
    throw new IllegalArgumentException("releaseState must be ONLINE or OFFLINE");
}

boolean isValidReleaseState(String s) {
    return "ONLINE".equals(s) || "OFFLINE".equals(s);
}

try {
    controller.releaseWorkflowDefinition(loginUser, projectCode, code, releaseState);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("The releaseState")) {
        log.error("Use exactly ONLINE or OFFLINE: {}", e.getMessage());
    }
}

When it happens

Trigger: POST /projects/{code}/workflow-definition/{wfCode}/release with releaseState not equal to ONLINE or OFFLINE (e.g. 'online' lowercase, 'ENABLE', or an empty value).

Common situations: Scripts using 'ONLINE'/'OFFLINE' synonyms like 'PUBLISH'/'UNPUBLISH'; case or whitespace mistakes; older API clients using a state name removed in a version upgrade.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• The execType: {execType} is invalid
• 10105
• WORKFLOW_DEFINITION_NOT_EXIST
• requestType is not a valid value
• contentType is not a valid value

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