alibaba/canal · error · IllegalArgumentException

period must be positive, given: {period}

Error message

period must be positive, given: {period}

What it means

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.

Source

Thrown at parse/src/main/java/com/alibaba/otter/canal/parse/index/FileMixedLogPositionManager.java:61

    private Map<String, File>        dataFileCaches;

    private ScheduledExecutorService executorService;

    @SuppressWarnings("serial")
    private final LogPosition        nullPosition = new LogPosition() {
                                                  };

    private MemoryLogPositionManager memoryLogPositionManager;

    private long                     period;
    private Set<String>              persistTasks;

    public FileMixedLogPositionManager(File dataDir, long period, MemoryLogPositionManager memoryLogPositionManager){
        if (dataDir == null) {
            throw new NullPointerException("null dataDir");
        }
        if (period <= 0) {
            throw new IllegalArgumentException("period must be positive, given: " + period);
        }
        if (memoryLogPositionManager == null) {
            throw new NullPointerException("null memoryLogPositionManager");
        }
        this.dataDir = dataDir;
        this.period = period;
        this.memoryLogPositionManager = memoryLogPositionManager;

        this.dataFileCaches = MigrateMap.makeComputingMap(this::getDataFile);

        this.executorService = Executors.newScheduledThreadPool(1);
        this.persistTasks = Collections.synchronizedSet(new HashSet<>());
    }

    @Override
    public void start() {
        super.start();

View on GitHub (pinned to 87be50e876)

Solutions

1. Set the period property to a positive millisecond value (e.g. 1000 for 1 second) in canal.conf / instance properties.
2. If building manually, ensure the period argument is > 0 and expressed in milliseconds.
3. Check that the property is actually read by the config loader (correct key name, no typo).

Example fix

// before
new FileMixedLogPositionManager(dir, 0, memoryMgr);

// after
long period = 1000; // ms
if (period <= 0) throw new IllegalArgumentException("period must be > 0");
new FileMixedLogPositionManager(dir, period, memoryMgr);

if (period <= 0) throw new IllegalArgumentException("period must be > 0: " + period);
new FileMixedLogPositionManager(dir, period, memoryMgr);

boolean isPositivePeriod(long p) { return p > 0; }

When it happens

Trigger: 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).

Common situations: `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").

Related errors

• period must be positive, given: {period}
• nul secondary LogPositionManager
• null dataDir
• null memoryLogPositionManager
• null metaManager

AI-assisted analysis of alibaba/canal@87be50e876 (2026-08-14). Data as JSON: /api/errors/8d9d67cba3dc5474. Report an issue: GitHub.