aeron-io/aeron · error · IllegalArgumentException
EINVAL
EINVAL
Error message
unknown action
What it means
Thrown by ImageControlledFragmentAssembler::handlerCallback when the ControlledPollAction returned by the user's image controlled fragment handler does not correspond to any value handled in the mapping switch. As with the non-Image assembler, an unrecognized action is an internal invariant violation. The wrapper cannot convert the action to the C AERON_ACTION_* constant.
Solutions
- Ensure every code path of your handler returns a defined ControlledPollAction (ABORT, COMMIT, BREAK, CONTINUE).
- Never cast arbitrary integers to ControlledPollAction; always use the enum constants.
- Initialize any action variable and add a default return for all branches.
- Rebuild handler and library with the same Aeron version so enum definitions match.
Example fix
// before ControlledPollAction action; if (x) action = ControlledPollAction::COMMIT; return action; // after if (x) return ControlledPollAction::COMMIT; return ControlledPollAction::CONTINUE;
Defensive patterns
Strategy: validation
Validate before calling
ControlledPollAction sanitize(ControlledPollAction a) {
switch (a) {
case ControlledPollAction::ABORT:
case ControlledPollAction::COMMIT:
case ControlledPollAction::BREAK:
case ControlledPollAction::CONTINUE:
return a;
default:
return ControlledPollAction::CONTINUE;
}
} Type guard
bool isDefinedAction(ControlledPollAction a) {
switch (a) {
case ControlledPollAction::ABORT:
case ControlledPollAction::COMMIT:
case ControlledPollAction::BREAK:
case ControlledPollAction::CONTINUE:
return true;
default:
return false;
}
} Try / catch
try { image.controlledPoll(handler); }
catch (const aeron::util::IllegalArgumentException& e) {
if (std::string(e.what()) == "unknown action") {
log("image handler returned undefined action");
}
} Prevention
- Every handler return path must yield a defined ControlledPollAction
- Use enum constants, never integer casts
- Initialize action variables
- Keep handler and library compiled from one Aeron version
When it happens
Trigger: An image-controlled fragment handler returning an out-of-range ControlledPollAction (uninitialized variable, cast integer, or an enumerator unknown to the compiled wrapper switch).
Common situations: Custom per-Image handlers with a missing return path, uninitialized action variables, or handler code compiled against different Aeron headers than the linked library.
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
AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12).
Data as JSON: /api/errors/e48da29d8e77caa5.
Report an issue: GitHub.
Appendix: source
Thrown at aeron-client/src/main/cpp_wrapper/ImageControlledFragmentAssembler.h:107
ControlledPollAction action = assembler->m_delegate(bufferWrapper, 0, (util::index_t)length, headerWrapper);
switch (action)
{
case ControlledPollAction::ABORT:
return AERON_ACTION_ABORT;
break;
case ControlledPollAction::BREAK:
return AERON_ACTION_BREAK;
break;
case ControlledPollAction::COMMIT:
return AERON_ACTION_COMMIT;
break;
case ControlledPollAction::CONTINUE:
return AERON_ACTION_CONTINUE;
break;
}
throw IllegalArgumentException("unknown action", SOURCEINFO, EINVAL);
}
ControlledPollAction onFragment(AtomicBuffer &buffer, util::index_t offset, util::index_t length, Header &header)
{
aeron_controlled_fragment_handler_action_t action = aeron_image_controlled_fragment_assembler_handler(
m_fragment_assembler,
buffer.buffer() + offset,
length,
header.hdr());
switch (action)
{
case AERON_ACTION_ABORT:
return ControlledPollAction::ABORT;
break;
case AERON_ACTION_BREAK:
return ControlledPollAction::BREAK;
break;View on GitHub (pinned to 6d60124e15)