{"record":{"id":"8d9d67cba3dc5474","repo":"alibaba/canal","slug":"period-must-be-positive-given-period","errorCode":null,"errorMessage":"period must be positive, given: {period}","messagePattern":"period must be positive, given: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"parse/src/main/java/com/alibaba/otter/canal/parse/index/FileMixedLogPositionManager.java","lineNumber":61,"sourceCode":"    private Map<String, File>        dataFileCaches;\n\n    private ScheduledExecutorService executorService;\n\n    @SuppressWarnings(\"serial\")\n    private final LogPosition        nullPosition = new LogPosition() {\n                                                  };\n\n    private MemoryLogPositionManager memoryLogPositionManager;\n\n    private long                     period;\n    private Set<String>              persistTasks;\n\n    public FileMixedLogPositionManager(File dataDir, long period, MemoryLogPositionManager memoryLogPositionManager){\n        if (dataDir == null) {\n            throw new NullPointerException(\"null dataDir\");\n        }\n        if (period <= 0) {\n            throw new IllegalArgumentException(\"period must be positive, given: \" + period);\n        }\n        if (memoryLogPositionManager == null) {\n            throw new NullPointerException(\"null memoryLogPositionManager\");\n        }\n        this.dataDir = dataDir;\n        this.period = period;\n        this.memoryLogPositionManager = memoryLogPositionManager;\n\n        this.dataFileCaches = MigrateMap.makeComputingMap(this::getDataFile);\n\n        this.executorService = Executors.newScheduledThreadPool(1);\n        this.persistTasks = Collections.synchronizedSet(new HashSet<>());\n    }\n\n    @Override\n    public void start() {\n        super.start();\n","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/alibaba/canal/blob/87be50e87686a3e8af08c368d0e1ffd1f59eb04a/parse/src/main/java/com/alibaba/otter/canal/parse/index/FileMixedLogPositionManager.java#L43-L79","documentation":"FileMixedLogPositionManager runs a scheduled task every `period` milliseconds to flush in-memory positions to disk. A period of zero or a negative value would either never run or break the scheduler, so the constructor throws IllegalArgumentException. The value must be a positive number of milliseconds.","triggerScenarios":"Constructing FileMixedLogPositionManager with period <= 0. This occurs when the flush period property is unset (defaulting to 0), explicitly set to 0, or parsed incorrectly (e.g. a blank value coerced to 0).","commonSituations":"`canal.instance.position.flush.period` / `canal.zk.flush.interval` is omitted from config, or the user mistyped the units (entered seconds where milliseconds were expected and then set 0 to \"disable\").","solutions":["Set the period property to a positive millisecond value (e.g. 1000 for 1 second) in canal.conf / instance properties.","If building manually, ensure the period argument is > 0 and expressed in milliseconds.","Check that the property is actually read by the config loader (correct key name, no typo)."],"exampleFix":"// before\nnew FileMixedLogPositionManager(dir, 0, memoryMgr);\n\n// after\nlong period = 1000; // ms\nif (period <= 0) throw new IllegalArgumentException(\"period must be > 0\");\nnew FileMixedLogPositionManager(dir, period, memoryMgr);","handlingStrategy":"validation","validationCode":"if (period <= 0) throw new IllegalArgumentException(\"period must be > 0: \" + period);\nnew FileMixedLogPositionManager(dir, period, memoryMgr);","typeGuard":"boolean isPositivePeriod(long p) { return p > 0; }","tryCatchPattern":null,"preventionTips":["Give the flush-period config key a positive default (e.g. 1000ms).","Document the unit (milliseconds) next to the config key.","Validate all numeric config in one bootstrap validator."],"tags":["canal","log-position-manager","argument-validation","scheduler","configuration"],"backgroundTag":null,"analyzedSha":"87be50e87686a3e8af08c368d0e1ffd1f59eb04a","analyzedAt":"2026-08-14T04:30:11.918Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}