alibaba/canal · error · IllegalArgumentException

period must be positive, given: {period}

Error message

period must be positive, given: {period}

What it means

PeriodMixedLogPositionManager runs a scheduled executor every `period` milliseconds to push in-memory positions to ZooKeeper. A period of zero or less would disable or break the scheduler, so the constructor throws IllegalArgumentException.

Source

Thrown at parse/src/main/java/com/alibaba/otter/canal/parse/index/PeriodMixedLogPositionManager.java:47

    private long                        period;
    private Set<String>                 persistTasks;

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

    public PeriodMixedLogPositionManager(MemoryLogPositionManager memoryLogPositionManager,
                                         ZooKeeperLogPositionManager zooKeeperLogPositionManager, long period){
        if (memoryLogPositionManager == null) {
            throw new NullPointerException("null memoryLogPositionManager");
        }

        if (zooKeeperLogPositionManager == null) {
            throw new NullPointerException("null zooKeeperLogPositionManager");
        }

        if (period <= 0) {
            throw new IllegalArgumentException("period must be positive, given: " + period);
        }

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

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

        if (zooKeeperLogPositionManager.isStart()) {
            zooKeeperLogPositionManager.stop();
        }

        if (memoryLogPositionManager.isStart()) {

View on GitHub (pinned to 87be50e876)

Solutions

1. Set the period to a positive millisecond value (e.g. 1000) in the instance/canal config.
2. When building manually, pass a checked-positive long for the period argument.
3. Verify the property key name matches what the config loader reads.

Example fix

// before
new PeriodMixedLogPositionManager(memMgr, zkMgr, 0);

// after
long period = 1000; // ms
if (period <= 0) throw new IllegalArgumentException("period must be > 0");
new PeriodMixedLogPositionManager(memMgr, zkMgr, period);

if (period <= 0) throw new IllegalArgumentException("period must be > 0: " + period);
new PeriodMixedLogPositionManager(memMgr, zkMgr, period);

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

When it happens

Trigger: Constructing PeriodMixedLogPositionManager with period <= 0. Occurs when the flush interval property is unset (defaults to 0), mistyped, or the user set it to 0 intending to disable flushing.

Common situations: `canal.zk.flush.interval` omitted or set to 0; units confusion (seconds vs milliseconds); config placeholder that resolved to empty.

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/466c23e4a7898ebb. Report an issue: GitHub.