{"record":{"id":"5287926d765cc681","repo":"kestra-io/kestra","slug":"invalid-target-state-state-valid-states-are","errorCode":null,"errorMessage":"Invalid target state: {state}. Valid states are: {VALID_TARGET_STATES}","messagePattern":"Invalid target state: (.+?)\\. Valid states are: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/io/kestra/core/services/ConcurrencyLimitService.java","lineNumber":35,"sourceCode":"\n    @Inject\n    private ExecutionQueuedStateStore executionQueuedStateStore;\n\n    /**\n     * Unqueue a queued execution.\n     *\n     * @throws IllegalArgumentException in case the execution is not queued or is transitioned to an unsupported state.\n     */\n    public Execution unqueue(Execution execution, State.Type state) {\n        if (execution.getState().getCurrent() != State.Type.QUEUED) {\n            throw new IllegalArgumentException(\"Only QUEUED execution can be unqueued\");\n        }\n\n        state = (state == null) ? State.Type.RUNNING : state;\n\n        // Validate the target state, throwing an exception if the state is invalid\n        if (!VALID_TARGET_STATES.contains(state)) {\n            throw new IllegalArgumentException(\"Invalid target state: \" + state + \". Valid states are: \" + VALID_TARGET_STATES);\n        }\n\n        executionQueuedStateStore.remove(execution);\n\n        return execution.withState(state);\n    }\n}\n","sourceCodeStart":17,"sourceCodeEnd":43,"githubUrl":"https://github.com/kestra-io/kestra/blob/823fada9274c4f9c251ea0a516460a4f7d958032/core/src/main/java/io/kestra/core/services/ConcurrencyLimitService.java#L17-L43","documentation":"The `ConcurrencyLimitService.unqueue()` method only allows transitions to three target states: `RUNNING`, `CANCELLED`, and `FAILED` (defined in `VALID_TARGET_STATES`). If any other `State.Type` is passed (e.g., `SUCCESS`, `PAUSED`, `KILLED`), an `IllegalArgumentException` is thrown. These states represent the valid outcomes of releasing a queued execution.","triggerScenarios":"Calling `unqueue(execution, State.Type.SUCCESS)` or `unqueue(execution, State.Type.PAUSED)`. Passing a state that is semantically inappropriate for an unqueue operation (SUCCESS must come from task completion, not from unqueuing).","commonSituations":"A developer assumes any terminal state is valid. A caller tries to mark a queued execution as SUCCESS to skip it, but SUCCESS is not a valid unqueue target.","solutions":["Use one of the valid target states: RUNNING (start it), CANCELLED (cancel it), or FAILED (fail it).","For SUCCESS, let the execution run and complete normally rather than forcing the state at unqueue time.","If you need PAUSED, the execution must run first and then be paused, not transitioned directly from QUEUED."],"exampleFix":"// before\nexecutionService.unqueue(execution, State.Type.SUCCESS);\n// after\nexecutionService.unqueue(execution, State.Type.RUNNING);","handlingStrategy":"validation","validationCode":"// Validate target state before calling unqueue\nimport io.kestra.core.models.flows.State;\nimport java.util.EnumSet;\n\nprivate static final Set<State.Type> VALID = EnumSet.of(State.Type.RUNNING, State.Type.CANCELLED, State.Type.FAILED);\n\npublic static State.Type validateUnqueueTargetState(State.Type state) {\n    if (state == null) return State.Type.RUNNING;\n    if (!VALID.contains(state)) {\n        throw new IllegalArgumentException(\"Invalid target state: \" + state + \". Valid: \" + VALID);\n    }\n    return state;\n}","typeGuard":"const VALID_UNQUEUE_STATES = new Set(['RUNNING', 'CANCELLED', 'FAILED']);\n\nfunction isValidUnqueueState(state: string): boolean {\n    return VALID_UNQUEUE_STATES.has(state);\n}","tryCatchPattern":null,"preventionTips":["Only pass RUNNING, CANCELLED, or FAILED as the target state for unqueue().","Default to RUNNING when the intent is to start the execution.","Do not try to force SUCCESS or PAUSED from QUEUED — these are not valid unqueue transitions."],"tags":["concurrency","execution","state-machine","validation"],"backgroundTag":null,"analyzedSha":"823fada9274c4f9c251ea0a516460a4f7d958032","analyzedAt":"2026-08-14T06:15:17.947Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}