alibaba/canal · error · CanalParseException

download binlog is null

Error message

download binlog is null

What it means

Thrown from BinlogDownloadQueue.tryOne() when binlogList.poll() returns null — the RDS binlog download queue has no binlog files available to download. This is used in Alibaba Cloud RDS offline binlog download mode, where Canal fetches historical binlog files via the RDS OpenAPI rather than connecting to a live replication stream.

Source

Thrown at parse/src/main/java/com/alibaba/otter/canal/parse/inbound/mysql/rds/BinlogDownloadQueue.java:95

    public void cleanDir() throws IOException {
        File destDirFile = new File(destDir);
        FileUtils.forceMkdir(destDirFile);
        FileUtils.cleanDirectory(destDirFile);
    }

    public void silenceDownload() {
        if (downloadThread != null) {
            return;
        }
        downloadThread = new Thread(new DownloadThread(), "download-" + destDir);
        downloadThread.setDaemon(true);
        downloadThread.start();
    }

    public BinlogFile tryOne() throws Throwable {
        BinlogFile binlogFile = binlogList.poll();
        if (binlogFile == null) {
            throw new CanalParseException("download binlog is null");
        }
        download(binlogFile);
        hostId = binlogFile.getHostInstanceID();
        this.currentSize++;
        return binlogFile;
    }

    public void notifyNotMatch() {
        this.currentSize--;
        filter(hostId);
    }

    private void filter(String hostInstanceId) {
        Iterator<BinlogFile> it = binlogList.iterator();
        while (it.hasNext()) {
            BinlogFile bf = it.next();
            if (bf.getHostInstanceID().equalsIgnoreCase(hostInstanceId)) {
                it.remove();

View on GitHub (pinned to 87be50e876)

Solutions

  1. Verify the RDS instance ID and region in the canal configuration match the actual RDS instance.
  2. Check the requested time range — ensure it falls within the RDS binlog retention window (typically 7-30 days).
  3. Ensure silenceDownload() was called before tryOne() to start the background download thread.
  4. Verify the RDS AccessKey/SecretKey have permissions to call the DescribeBinlogFiles API.

Example fix

# before — wrong instance id or time range
canal.instance.rds.instanceId=rm-xxxxx
canal.instance.rds.startTime=2024-01-01T00:00:00Z

# after — correct instance id and valid time range
canal.instance.rds.instanceId=rm-bp1xxxxxxxxxxxx
# ensure time range is within RDS retention
canal.instance.rds.startTime=2024-06-01T00:00:00Z
Defensive patterns

Strategy: retry

Validate before calling

// Before calling tryOne(), ensure the download thread has started and the queue is populated
downloadQueue.silenceDownload();
// Wait briefly for the first download to populate the queue
if (downloadQueue.size() == 0) {
    Thread.sleep(5000); // give the download thread time to fetch results
}
if (downloadQueue.size() == 0) {
    throw new IllegalStateException("No binlog files available from RDS for the configured time range");
}

Try / catch

int retries = 0;
while (retries < 5) {
    try {
        BinlogFile file = downloadQueue.tryOne();
        break;
    } catch (CanalParseException e) {
        if (e.getMessage().contains("download binlog is null")) {
            retries++;
            Thread.sleep(retries * 3000L);
            continue;
        }
        throw e;
    }
}

Prevention

When it happens

Trigger: tryOne() is called (typically during the first attempt to get a binlog file for processing) but binlogList (the internal queue of BinlogFile objects fetched from RDS API) is empty. This means the RDS API returned no binlog files for the requested time range, or the download thread hasn't populated the queue yet.

Common situations: The RDS binlog query parameters (start/end time, instance ID) don't match any available binlog files. The download thread (silenceDownload) hasn't started or hasn't fetched results yet. The RDS API returned an empty list because all binlogs in the requested range were purged. The instance ID is wrong.

Related errors

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