{"record":{"id":"4b7df31775e1b18a","repo":"apache/seatunnel","slug":"error-handler-max-error-ratio-must-be-between-0-0","errorCode":null,"errorMessage":"error handler max_error_ratio must be between 0.0 and 1.0, but was %s","messagePattern":"error handler max_error_ratio must be between 0\\.0 and 1\\.0, but was (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/task/error/ErrorHandlerConfigUtil.java","lineNumber":68,"sourceCode":"            return disabledConfig();\n        }\n\n        ReadonlyConfig envConfig = ReadonlyConfig.fromMap(envOptions);\n        Map<String, Object> root = envConfig.getSourceMap();\n\n        Map<String, Object> global =\n                getNestedMap(root, \"error_handler\").orElse(Collections.emptyMap());\n\n        String stageKey =\n                stageType == StageType.TRANSFORM ? \"transform_error_handler\" : \"sink_error_handler\";\n        Map<String, Object> stage = getNestedMap(root, stageKey).orElse(Collections.emptyMap());\n\n        String modeStr = getString(stage, global, \"mode\", \"DISABLE\");\n        ErrorHandlerMode mode = ErrorHandlerMode.fromString(modeStr);\n\n        double maxErrorRatio = getDouble(stage, global, \"max_error_ratio\", 0.0d);\n        if (maxErrorRatio < 0.0d || maxErrorRatio > 1.0d) {\n            throw new IllegalArgumentException(\n                    \"error handler max_error_ratio must be between 0.0 and 1.0, but was \"\n                            + maxErrorRatio);\n        }\n        int maxErrorRatioMinRecords =\n                getNonNegativeInt(\n                        stage,\n                        global,\n                        \"max_error_ratio_min_records\",\n                        DEFAULT_MAX_ERROR_RATIO_MIN_RECORDS);\n        long maxErrorRecords = getLong(stage, global, \"max_error_records\", 0L);\n        if (maxErrorRecords < 0L) {\n            throw new IllegalArgumentException(\n                    \"error handler max_error_records must be non-negative, but was \"\n                            + maxErrorRecords);\n        }\n\n        int queueCapacity = getNonNegativeInt(stage, global, \"queue_capacity\", 10000);\n        String overflowStr = getString(stage, global, \"queue_overflow_policy\", \"FAIL\");","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/task/error/ErrorHandlerConfigUtil.java#L50-L86","documentation":"IllegalArgumentException from ErrorHandlerConfigUtil.buildStageConfig when the configured max_error_ratio is outside the legal [0.0, 1.0] range. max_error_ratio is a fraction of rows allowed to fail, so values like 5 or 50 (percent-style) are rejected at config-parse time before the job starts.","triggerScenarios":"Setting env.error-handler.max_error_ratio (globally or per stage) to a negative value or a value > 1.0, e.g. 5 meaning '5%' instead of 0.05.","commonSituations":"Users writing percentage values (50 instead of 0.5); typo'd decimals like 1.5; copy-pasting configs between systems with different ratio conventions.","solutions":["Express the ratio as a fraction between 0.0 and 1.0 (e.g. 5% → 0.05).","Check both global error-handler config and stage-level overrides for the bad value.","Use max_error_records instead if you want an absolute count rather than a ratio."],"exampleFix":"// before\nerror-handler { max_error_ratio = 5 }\n// after\nerror-handler { max_error_ratio = 0.05 }","handlingStrategy":"validation","validationCode":"double r = config.getDouble(\"max_error_ratio\");\nif (r < 0.0 || r > 1.0) throw new IllegalArgumentException(\"max_error_ratio must be a fraction in [0.0,1.0], got \" + r);","typeGuard":"boolean isValidRatio(Object v) { return v instanceof Number n && n.doubleValue() >= 0.0 && n.doubleValue() <= 1.0; }","tryCatchPattern":"try { buildStageConfig(stage, global); } catch (IllegalArgumentException e) { if (e.getMessage().contains(\"max_error_ratio\")) { fixRatioConfig(); } }","preventionTips":["Always express ratios as fractions (5% → 0.05), never percentages","Validate error-handler config before job submission","Search both global and stage-level blocks for the option"],"tags":["config","validation","ratio"],"backgroundTag":"value-out-of-range","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}