{"record":{"id":"26e3685819770b7c","repo":"apache/flink","slug":"the-filter-factor-cannot-be-smaller-than-zero","errorCode":null,"errorMessage":"The filter factor cannot be smaller than zero.","messagePattern":"The filter factor cannot be smaller than zero\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"flink-core/src/main/java/org/apache/flink/api/common/operators/CompilerHints.java","lineNumber":93,"sourceCode":"    public float getAvgOutputRecordSize() {\n        return this.avgOutputRecordSize;\n    }\n\n    public void setAvgOutputRecordSize(float avgOutputRecordSize) {\n        if (avgOutputRecordSize <= 0) {\n            throw new IllegalArgumentException(\"The size of produced records must be positive.\");\n        }\n\n        this.avgOutputRecordSize = avgOutputRecordSize;\n    }\n\n    public float getFilterFactor() {\n        return filterFactor;\n    }\n\n    public void setFilterFactor(float filterFactor) {\n        if (filterFactor < 0) {\n            throw new IllegalArgumentException(\"The filter factor cannot be smaller than zero.\");\n        }\n\n        this.filterFactor = filterFactor;\n    }\n\n    // --------------------------------------------------------------------------------------------\n    //  Uniqueness\n    // --------------------------------------------------------------------------------------------\n\n    /**\n     * Gets the FieldSets that are unique\n     *\n     * @return List of FieldSet that are unique\n     */\n    public Set<FieldSet> getUniqueFields() {\n        return this.uniqueFields;\n    }\n","sourceCodeStart":75,"sourceCodeEnd":111,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/api/common/operators/CompilerHints.java#L75-L111","documentation":"Thrown by CompilerHints.setFilterFactor() when the supplied value is negative. The filter factor is an optimizer hint estimating the fraction of input records a filter/select operator retains (e.g. 0.5 = half survive, 0.0 = all dropped, 1.0 = none). The default is -1 (unset); any explicit value must be >= 0 so the optimizer's cardinality estimate stays non-negative.","triggerScenarios":"Calling Operator.getCompilerHints().setFilterFactor(x) with x < 0, or passing a computed ratio (dropped/total) that evaluates negative due to an off-by-one or a total count of zero producing a negative intermediate.","commonSituations":"Setting per-operator selectivity hints in the old DataSet API; computing a filter factor from job statistics where the denominator is 0 or negative; copying hint values from a config that allowed negative sentinels.","solutions":["Ensure the value is in [0.0, 1.0]; a factor of 0 is valid and means all records are filtered out.","Guard the assignment: only call setFilterFactor when your computed value is >= 0, and leave it unset (default -1) when unknown.","If using a ratio like retained/total, special-case total==0 to skip the hint instead of computing a negative ratio."],"exampleFix":"// before\nhints.setFilterFactor(passed - total);\n// after\nif (total > 0 && passed >= 0) {\n    hints.setFilterFactor((float) passed / total);\n}","handlingStrategy":"validation","validationCode":"if (factor >= 0f) {\n    hints.setFilterFactor(factor);\n} else {\n    // leave unset (default -1) when unknown\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat the filter factor as a ratio in [0,1]; never pass raw counts or differences.","Compute the factor defensively: only assign when the denominator is strictly positive.","Document at the call site that 0 is valid (all records filtered) and negative is the only forbidden range."],"tags":["flink-core","compiler-hints","optimizer","dataset-api","validation"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}