{"record":{"id":"ed1ef8e20278e713","repo":"alibaba/Sentinel","slug":"param","errorCode":null,"errorMessage":"${param}","messagePattern":"\\$\\{param\\}","errorType":"exception","errorClass":"ParamFlowException","httpStatus":null,"severity":"warning","filePath":"sentinel-adapter/sentinel-api-gateway-adapter-common/src/main/java/com/alibaba/csp/sentinel/adapter/gateway/common/slot/GatewayFlowSlot.java","lineNumber":68,"sourceCode":"            return;\n        }\n\n        List<ParamFlowRule> rules = GatewayRuleManager.getConvertedParamRules(resourceWrapper.getName());\n        if (rules == null || rules.isEmpty()) {\n            return;\n        }\n\n        for (ParamFlowRule rule : rules) {\n            // Initialize the parameter metrics.\n            ParameterMetricStorage.initParamMetricsFor(resourceWrapper, rule);\n\n            if (!ParamFlowChecker.passCheck(resourceWrapper, rule, count, args)) {\n                String triggeredParam = \"\";\n                if (args.length > rule.getParamIdx()) {\n                    Object value = args[rule.getParamIdx()];\n                    triggeredParam = String.valueOf(value);\n                }\n                throw new ParamFlowException(resourceWrapper.getName(), triggeredParam, rule);\n            }\n        }\n    }\n\n    @Override\n    public void exit(Context context, ResourceWrapper resourceWrapper, int count, Object... args) {\n        fireExit(context, resourceWrapper, count, args);\n    }\n}\n","sourceCodeStart":50,"sourceCodeEnd":78,"githubUrl":"https://github.com/alibaba/Sentinel/blob/a3f40ba8e900c8489bd520274739f17235a7721c/sentinel-adapter/sentinel-api-gateway-adapter-common/src/main/java/com/alibaba/csp/sentinel/adapter/gateway/common/slot/GatewayFlowSlot.java#L50-L78","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Handle the ParamFlowException (BlockException) in your gateway callback (e.g. GatewayCallbackManager.setBlockHandler) and return a 429-style response","Raise the rule's count or reconfigure paramItem (paramIdx, parseStrategy) if the threshold is too strict","If the limit should be global rather than per-parameter-value, use a normal GatewayFlowRule without a paramItem","Verify paramIdx matches the actual argument index provided by your gateway adapter's request parser"],"exampleFix":"// before\n// no block handler registered -> exception propagates\n\n// after\nGatewayCallbackManager.setBlockHandler((exchange, t) -> Mono.defer(() -> {\n    Map<String, String> res = Collections.singletonMap(\"code\", \"429\");\n    return GatewayCallbackManager.writeJson(exchange.getResponse(), res);\n}));","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    entry = SphU.entry(resourceName, ResourceTypeConstants.COMMON_API_GATEWAY, args);\n} catch (ParamFlowException e) {\n    // parameter flow control tripped; e.getRuleFactor() / message identifies the hot param\n    return blockedResponse();\n} catch (BlockException e) {\n    return blockedResponse();\n}","preventionTips":["Always register a block handler via GatewayCallbackManager when using gateway rules","Tune paramItem thresholds with real traffic distributions before enforcing","Log which parameter value tripped the rule (it is embedded in the exception) to spot misconfigured paramIdx"],"tags":["gateway","param-flow","rate-limit","block-exception","sentinel"],"backgroundTag":null,"analyzedSha":"a3f40ba8e900c8489bd520274739f17235a7721c","analyzedAt":"2026-08-14T11:10:30.678Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}