apache/incubator-seata · error · IllegalArgumentException

@BusinessActionContextParameter 's params can not null

Error message

@BusinessActionContextParameter 's params can not null

What it means

Thrown by the compatible ActionInterceptorHandler when a TCC method parameter annotated with @BusinessActionContextParameter is null at invocation time. The interceptor needs the parameter's value to build the BusinessActionContext used for the two-phase commit/rollback, so null annotated arguments are rejected.

Source

Thrown at compatible/src/main/java/io/seata/integration/tx/api/interceptor/ActionInterceptorHandler.java:83

     * Extracting context data from parameters, add them to the context
     *
     * @param method    the method
     * @param arguments the arguments
     * @return the context
     */
    @Override
    protected Map<String, Object> fetchActionRequestContext(Method method, Object[] arguments) {
        Map<String, Object> context = new HashMap<>(8);

        Annotation[][] parameterAnnotations = method.getParameterAnnotations();
        for (int i = 0; i < parameterAnnotations.length; i++) {
            for (int j = 0; j < parameterAnnotations[i].length; j++) {
                if (parameterAnnotations[i][j] instanceof BusinessActionContextParameter) {
                    // get annotation
                    BusinessActionContextParameter annotation =
                            (BusinessActionContextParameter) parameterAnnotations[i][j];
                    if (arguments[i] == null) {
                        throw new IllegalArgumentException("@BusinessActionContextParameter 's params can not null");
                    }

                    // get param
                    Object paramObject = arguments[i];
                    if (paramObject == null) {
                        continue;
                    }

                    // load param by the config of annotation, and then put into the context
                    ActionContextUtil.loadParamByAnnotationAndPutToContext(
                            ParamType.PARAM, "", paramObject, annotation, context);
                }
            }
        }
        return context;
    }
}

View on GitHub (pinned to e01f97c6db)

Solutions

1. Pass a real value for every @BusinessActionContextParameter-annotated parameter.
2. If the value is genuinely optional, remove the annotation from that parameter.
3. For values generated earlier in the flow, ensure they are computed before the TCC method call.
4. For primitives, pass explicit defaults instead of relying on boxing nulls.

Example fix

// before
@TwoPhaseBusinessAction(name = "orderTcc", commitMethod = "commit", rollbackMethod = "rollback")
public boolean prepare(@BusinessActionContextParameter("orderId") String orderId, ...) {}
...
tccAction.prepare(null, ...); // throws

// after
String orderId = orderService.generateId();
tccAction.prepare(orderId, ...);

for (int i = 0; i < args.length; i++) {
    if (isAnnotatedWithBusinessActionContextParameter(method, i) && args[i] == null) {
        throw new IllegalArgumentException(
            "parameter '" + method.getParameters()[i].getName() + "' must not be null (context-propagated)");
    }
}

try {
    return tccAction.prepare(orderId, ...);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("BusinessActionContextParameter")) {
        throw new BusinessException("TCC context parameter missing — generate required ids before calling", e);
    }
    throw e;
}

When it happens

Trigger: Invoking a @TwoPhaseBusinessAction method where an argument carrying @BusinessActionContextParameter is null. The check is positional: for each annotated parameter index i, arguments[i] must be non-null.

Common situations: Business code calling its own TCC method with optional/defaulted nulls; passing null for a context-propagated field (e.g. orderId not yet generated); test harnesses invoking methods with placeholder nulls.

Related errors

• non-BusinessActionContext parameter should use annotation Bu
• TCC bean name cannot be null or empty
• name can't be null
• Two or more start states, ${target} and ${definitions.StartS
• URL must not be null or blank

AI-assisted analysis of apache/incubator-seata@e01f97c6db (2026-08-14). Data as JSON: /api/errors/8b8150e234e88771. Report an issue: GitHub.