apache/incubator-seata · error · IllegalArgumentException

Required request parameter '%s' is missing

Error message

Required request parameter '%s' is missing

What it means

Thrown by ParameterParser (Seata's built-in HTTP parameter binding used by the http-invocation/consumer endpoints) when a request parameter is marked required in the @Parameter metadata, the request carries no value for it, and no defaultValue is defined. It surfaces as IllegalArgumentException from the argument-resolution step before the handler runs. Steps 1-2 of the parser (present value, then defaultValue) both failed.

Source

Thrown at core/src/main/java/org/apache/seata/core/rpc/netty/http/ParameterParser.java:140

            String paramName = paramMetaData.getParamName();
            JsonNode jsonNode = Optional.ofNullable(paramMap.get("param"))
                    .map(body -> body.get(paramName))
                    .orElse(null);

            // Step 1: If body exists and contains paramName, use its value first
            if (jsonNode != null && !jsonNode.isNull()) {
                return OBJECT_MAPPER.convertValue(jsonNode, parameterType);
            }

            // Step 2: If the parameter is missing but a defaultValue is set, use the defaultValue
            String defaultValue = paramMetaData.getDefaultValue();
            if (defaultValue != null && !defaultValue.equals(DEFAULT_NONE)) {
                return OBJECT_MAPPER.convertValue(defaultValue, parameterType);
            }

            // Step 3: If the parameter is required but no value or defaultValue is provided, throw an exception
            if (paramMetaData.isRequired()) {
                throw new IllegalArgumentException("Required request parameter '" + paramName + "' is missing");
            }
            return null;
        } else {
            JsonNode paramNode = paramMap.get("param");
            if (paramNode != null) {
                JsonNode jsonNode = paramNode.get(parameterName);
                if (jsonNode != null) {
                    String value = jsonNode.asText(null);
                    return value != null ? OBJECT_MAPPER.convertValue(value, parameterType) : null;
                }
            }
            return null;
        }
    }
}

View on GitHub (pinned to e01f97c6db)

Solutions

  1. Add the missing parameter to the request with the exact name expected (parameterName) and a non-null value.
  2. If the field is genuinely optional, annotate the handler parameter with a defaultValue (not DEFAULT_NONE) or set required=false.
  3. Check Content-Type matches how you are sending the data (application/json for body, or query/form params) so the parser actually sees the field.
  4. Ensure the client does not serialize explicit nulls (configure ObjectMapper NON_NULL) when the value is absent.

Example fix

// before
GET /http-invoker/execute?arg0=hello           // 'arg1' is required -> IllegalArgumentException

// after
GET /http-invoker/execute?arg0=hello&arg1=42
Defensive patterns

Strategy: validation

Validate before calling

// caller-side check before invoking the Seata HTTP endpoint
Map<String, String> params = new HashMap<>();
params.put("arg0", "hello");
// 'arg1' is required by the handler:
if (!params.containsKey("arg1") || params.get("arg1") == null) {
    throw new IllegalArgumentException("Missing required request parameter 'arg1'");
}
// proceed with the call

Try / catch

try {
    Object result = httpInvocation.execute(params, returnType);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("is missing")) {
        // bad request: fix the outgoing payload, do not retry unchanged
        throw new BadRequestException(e.getMessage(), e);
    }
    throw e;
}

Prevention

When it happens

Trigger: Calling a Seata HTTP endpoint whose handler method has a parameter annotated as required (paramMetaData.isRequired()) and omitting that parameter from query params / form / JSON body; sending an explicit JSON null (jsonNode.isNull() path) also counts as missing; sending the parameter under a different name than parameterName.

Common situations: Hand-crafted curl/REST calls to the http endpoint forgetting a mandatory field; clients serializing a null field so it arrives as JSON null; renaming a request field without updating callers; content-type mismatch causing the JSON body to not be parsed into paramMap at all.

Related errors

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