{"record":{"id":"d9dc0de38d3e938e","repo":"alibaba/canal","slug":"download-binlog-is-null","errorCode":null,"errorMessage":"download binlog is null","messagePattern":"download binlog is null","errorType":"exception","errorClass":"CanalParseException","httpStatus":null,"severity":"error","filePath":"parse/src/main/java/com/alibaba/otter/canal/parse/inbound/mysql/rds/BinlogDownloadQueue.java","lineNumber":95,"sourceCode":"    public void cleanDir() throws IOException {\n        File destDirFile = new File(destDir);\n        FileUtils.forceMkdir(destDirFile);\n        FileUtils.cleanDirectory(destDirFile);\n    }\n\n    public void silenceDownload() {\n        if (downloadThread != null) {\n            return;\n        }\n        downloadThread = new Thread(new DownloadThread(), \"download-\" + destDir);\n        downloadThread.setDaemon(true);\n        downloadThread.start();\n    }\n\n    public BinlogFile tryOne() throws Throwable {\n        BinlogFile binlogFile = binlogList.poll();\n        if (binlogFile == null) {\n            throw new CanalParseException(\"download binlog is null\");\n        }\n        download(binlogFile);\n        hostId = binlogFile.getHostInstanceID();\n        this.currentSize++;\n        return binlogFile;\n    }\n\n    public void notifyNotMatch() {\n        this.currentSize--;\n        filter(hostId);\n    }\n\n    private void filter(String hostInstanceId) {\n        Iterator<BinlogFile> it = binlogList.iterator();\n        while (it.hasNext()) {\n            BinlogFile bf = it.next();\n            if (bf.getHostInstanceID().equalsIgnoreCase(hostInstanceId)) {\n                it.remove();","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/alibaba/canal/blob/87be50e87686a3e8af08c368d0e1ffd1f59eb04a/parse/src/main/java/com/alibaba/otter/canal/parse/inbound/mysql/rds/BinlogDownloadQueue.java#L77-L113","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the RDS instance ID and region in the canal configuration match the actual RDS instance.","Check the requested time range — ensure it falls within the RDS binlog retention window (typically 7-30 days).","Ensure silenceDownload() was called before tryOne() to start the background download thread.","Verify the RDS AccessKey/SecretKey have permissions to call the DescribeBinlogFiles API."],"exampleFix":"# before — wrong instance id or time range\ncanal.instance.rds.instanceId=rm-xxxxx\ncanal.instance.rds.startTime=2024-01-01T00:00:00Z\n\n# after — correct instance id and valid time range\ncanal.instance.rds.instanceId=rm-bp1xxxxxxxxxxxx\n# ensure time range is within RDS retention\ncanal.instance.rds.startTime=2024-06-01T00:00:00Z","handlingStrategy":"retry","validationCode":"// Before calling tryOne(), ensure the download thread has started and the queue is populated\ndownloadQueue.silenceDownload();\n// Wait briefly for the first download to populate the queue\nif (downloadQueue.size() == 0) {\n    Thread.sleep(5000); // give the download thread time to fetch results\n}\nif (downloadQueue.size() == 0) {\n    throw new IllegalStateException(\"No binlog files available from RDS for the configured time range\");\n}","typeGuard":null,"tryCatchPattern":"int retries = 0;\nwhile (retries < 5) {\n    try {\n        BinlogFile file = downloadQueue.tryOne();\n        break;\n    } catch (CanalParseException e) {\n        if (e.getMessage().contains(\"download binlog is null\")) {\n            retries++;\n            Thread.sleep(retries * 3000L);\n            continue;\n        }\n        throw e;\n    }\n}","preventionTips":["Always call silenceDownload() before tryOne() to start the background download thread.","Verify the RDS instance ID, region, and time range are correct and within the binlog retention window.","Ensure the AccessKey has permissions for the DescribeBinlogFiles RDS API."],"tags":["rds","alibaba-cloud","binlog-download","empty-queue","offline"],"backgroundTag":null,"analyzedSha":"87be50e87686a3e8af08c368d0e1ffd1f59eb04a","analyzedAt":"2026-08-14T04:30:11.918Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}