flowable/flowable-engine · error · FlowableIllegalArgumentException

Signal name is required.

Error message

Signal name is required.

What it means

FlowableIllegalArgumentException thrown by ExecutionCollectionResource.executeExecutionAction when the action is 'signal-event-received' but the request's signalName is null. The runtime service needs the signal name to fire the matching signal boundary/start event; it cannot proceed without it.

Solutions

1. Add "signalName" with the name of the signal defined in the process model.
2. Verify the field name is exactly 'signalName'.
3. Confirm the signal exists in the BPMN model and match its name exactly.
4. If variables are needed, keep them alongside a valid signalName: {"action":"signal-event-received","signalName":"...","variables":[...]}.

Example fix

// before
{"action": "signal-event-received", "variables": [{"name": "x", "value": 1}]}
// after
{"action": "signal-event-received", "signalName": "orderSignal", "variables": [{"name": "x", "value": 1}]}

if (body.action === 'signal-event-received' && (!body.signalName || typeof body.signalName !== 'string')) {
  throw new Error('signalName is required when action is signal-event-received');
}

function hasSignalName(b: { signalName?: unknown }): b is { signalName: string } {
  return typeof b.signalName === 'string' && b.signalName.length > 0;
}

try {
  await restClient.post('/runtime/executions', body);
} catch (e) {
  if (e.response && e.response.status === 400 && /Signal name is required/.test(e.response.data && e.response.data.message || '')) {
    console.error('Request body must include a non-null "signalName"');
  }
  throw e;
}

When it happens

Trigger: POST /runtime/executions with body {"action":"signal-event-received"} lacking the 'signalName' field, or with signalName explicitly set to null.

Common situations: Omitting signalName while including 'variables'; renaming the field in client code ('name' or 'signal' instead of 'signalName'); template/config-driven payloads where the signal name binding is empty.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Signal name is required
• A request body was expected when executing the form submit.
• Attachment name is required.
• Error converting request body to RestVariable instance
• Id cannot be null.

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/c406da0f15d78670. Report an issue: GitHub.

Appendix: source

Thrown at modules/flowable-rest/src/main/java/org/flowable/rest/service/api/runtime/process/ExecutionCollectionResource.java:149

    //FIXME Documentation ?
    @ApiOperation(value = "Signal event received", tags = { "Executions" }, code = 204)
    @ApiResponses(value = {
            @ApiResponse(code = 204, message = "Indicates request was successful and the executions are returned"),
            @ApiResponse(code = 404, message = "Indicates a parameter was passed in the wrong format . The status-message contains additional information.")
    })
    @PutMapping(value = "/runtime/executions")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void executeExecutionAction(@RequestBody ExecutionActionRequest actionRequest) {
        if (restApiInterceptor != null) {
            restApiInterceptor.doExecutionActionRequest(actionRequest);
        }
        
        if (!ExecutionActionRequest.ACTION_SIGNAL_EVENT_RECEIVED.equals(actionRequest.getAction())) {
            throw new FlowableIllegalArgumentException("Illegal action: '" + actionRequest.getAction() + "'.");
        }

        if (actionRequest.getSignalName() == null) {
            throw new FlowableIllegalArgumentException("Signal name is required.");
        }

        if (actionRequest.getVariables() != null) {
            runtimeService.signalEventReceived(actionRequest.getSignalName(), getVariablesToSet(actionRequest.getVariables()));
        } else {
            runtimeService.signalEventReceived(actionRequest.getSignalName());
        }
    }
}

View on GitHub (pinned to d6d39ce1c6)