alibaba/canal · error · CanalMetaManagerException

dir[{}] can not read/write

Error message

dir[{}] can not read/write

What it means

Thrown by FileMixedMetaManager.start when the configured dataDir either cannot be created or, after creation, lacks read/write permission for the Canal process user. This meta manager persists client identity/cursor data to files on disk, so an inaccessible directory blocks startup entirely.

Source

Thrown at meta/src/main/java/com/alibaba/otter/canal/meta/FileMixedMetaManager.java:69

    @SuppressWarnings("serial")
    private final Position           nullCursor   = new Position() {
                                                  };
    private long                     period       = 1000;                                               // 单位ms
    private Set<ClientIdentity>      updateCursorTasks;

    public void start() {
        super.start();
        Assert.notNull(dataDir);
        if (!dataDir.exists()) {
            try {
                FileUtils.forceMkdir(dataDir);
            } catch (IOException e) {
                throw new CanalMetaManagerException(e);
            }
        }

        if (!dataDir.canRead() || !dataDir.canWrite()) {
            throw new CanalMetaManagerException("dir[" + dataDir.getPath() + "] can not read/write");
        }

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

        executor = Executors.newScheduledThreadPool(1);
        destinations = MigrateMap.makeComputingMap(this::loadClientIdentity);

        cursors = MigrateMap.makeComputingMap(clientIdentity -> {
            Position position = loadCursor(clientIdentity.getDestination(), clientIdentity);
            if (position == null) {
                return nullCursor; // 返回一个空对象标识，避免出现异常
            } else {
                return position;
            }
        });

        updateCursorTasks = Collections.synchronizedSet(new HashSet<>());

View on GitHub (pinned to 87be50e876)

Solutions

1. Check the configured dataDir path in canal.properties/instance properties and confirm it resolves as intended.
2. Grant the Canal process user read+write (and traverse) permissions on that directory: chown/chmod as needed.
3. Ensure the parent path exists so forceMkdir does not fail, or point dataDir at a writable location (e.g. under /home/canal/canal-data).
4. If running in a container, confirm the mounted volume is writable and not read-only.

Example fix

# before (read-only or root-owned)
canal.instance.global.meta.dir = /var/lib/canal

# after (writable by canal user)
canal.instance.global.meta.dir = /home/canal/canal-data
# plus: chown -R canal:canal /home/canal/canal-data

java.io.File dir = new java.io.File(dataDirPath);
if (!dir.exists() && !dir.mkdirs()) throw new IllegalStateException("cannot create meta dir: " + dir);
if (!dir.canRead() || !dir.canWrite()) throw new IllegalStateException("meta dir not rw: " + dir);

try { metaManager.start(); }
catch (CanalMetaManagerException e) {
    if (e.getMessage().contains("can not read/write")) { fixPermissions(dataDirPath); metaManager.start(); }
    else throw e;
}

When it happens

Trigger: FileMixedMetaManager.start() runs during instance startup. It first tries FileUtils.forceMkdir(dataDir) (an IOException there throws CanalMetaManagerException wrapping it). If the dir exists/created but dataDir.canRead() or dataDir.canWrite() is false, it throws this exact message.

Common situations: canal.mq.flatMessage or the meta dataDir (canal.instance.global.meta.dir or similar) points at a path the canal user cannot write (owned by root, read-only mount, SELinux denial), or the parent path does not exist and mkdir lacks permission.

Related errors

• Binlog index missing or unreadable; {}
• can't find start position for {}
• dir[{path}] can not read/write
• canal.adminUser is empty , pls check https://github.com/alib
• canal.adminPasswd is empty , pls check https://github.com/al

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