alibaba/Sentinel · warning · ParamFlowException

${param}

Error message

${param}

What it means

This is Sentinel's gateway hot-parameter flow-control rejection: GatewayFlowSlot.entry() converts configured GatewayFlowRule entries into ParamFlowRules and runs ParamFlowChecker.passCheck against the request parameters (args). When a rule's threshold for the parameter at paramIdx is exceeded, it throws ParamFlowException(resourceName, triggeredParam, rule) — a BlockException subtype. The '${param}' in the message is the offending parameter value that tripped the rule. This is normal rate-limiting behavior, not a malfunction.

Source

Thrown at sentinel-adapter/sentinel-api-gateway-adapter-common/src/main/java/com/alibaba/csp/sentinel/adapter/gateway/common/slot/GatewayFlowSlot.java:68

            return;
        }

        List<ParamFlowRule> rules = GatewayRuleManager.getConvertedParamRules(resourceWrapper.getName());
        if (rules == null || rules.isEmpty()) {
            return;
        }

        for (ParamFlowRule rule : rules) {
            // Initialize the parameter metrics.
            ParameterMetricStorage.initParamMetricsFor(resourceWrapper, rule);

            if (!ParamFlowChecker.passCheck(resourceWrapper, rule, count, args)) {
                String triggeredParam = "";
                if (args.length > rule.getParamIdx()) {
                    Object value = args[rule.getParamIdx()];
                    triggeredParam = String.valueOf(value);
                }
                throw new ParamFlowException(resourceWrapper.getName(), triggeredParam, rule);
            }
        }
    }

    @Override
    public void exit(Context context, ResourceWrapper resourceWrapper, int count, Object... args) {
        fireExit(context, resourceWrapper, count, args);
    }
}

View on GitHub (pinned to a3f40ba8e9)

Solutions

1. Handle the ParamFlowException (BlockException) in your gateway callback (e.g. GatewayCallbackManager.setBlockHandler) and return a 429-style response
2. Raise the rule's count or reconfigure paramItem (paramIdx, parseStrategy) if the threshold is too strict
3. If the limit should be global rather than per-parameter-value, use a normal GatewayFlowRule without a paramItem
4. Verify paramIdx matches the actual argument index provided by your gateway adapter's request parser

Example fix

// before
// no block handler registered -> exception propagates

// after
GatewayCallbackManager.setBlockHandler((exchange, t) -> Mono.defer(() -> {
    Map<String, String> res = Collections.singletonMap("code", "429");
    return GatewayCallbackManager.writeJson(exchange.getResponse(), res);
}));

try {
    entry = SphU.entry(resourceName, ResourceTypeConstants.COMMON_API_GATEWAY, args);
} catch (ParamFlowException e) {
    // parameter flow control tripped; e.getRuleFactor() / message identifies the hot param
    return blockedResponse();
} catch (BlockException e) {
    return blockedResponse();
}

When it happens

Trigger: A GatewayFlowRule (param-flow item, e.g. threshold per CV/value) on a route or API group where the argument at rule.getParamIdx() (e.g. a header, URL param, or client IP) exceeds count within the duration window; e.g. more than N requests per second with the same ?uid=123 value.

Common situations: API gateway (Spring Cloud Gateway / Zuul) with gateway rules limiting per-user or per-IP parameters; load tests tripping parameter thresholds; misconfigured paramIdx pointing at a heavily repeated value (like a shared proxy IP).

Related errors

• maxTokens should > 0, but given:
• intervalMillis should be at least 1000, but given:
• Invalid intervalUnit: {}
• ${name} is null
• keys empty or null: ${keys}

AI-assisted analysis of alibaba/Sentinel@a3f40ba8e9 (2026-08-14). Data as JSON: /api/errors/ed1ef8e20278e713. Report an issue: GitHub.