alibaba/canal · error · CanalParseException

fetch table meta failed. table: {}

Error message

fetch table meta failed. table: {}

What it means

Thrown from the Guava LoadingCache loader in TableMetaCache.createLocalCache() when both the initial getTableMetaByDB() call and the retry (after connection.reconnect()) fail with an IOException. The cache loader first tries to query 'show create table', and on any Throwable it reconnects and retries once. If the retry also fails, this CanalParseException wraps the second IOException.

Source

Thrown at parse/src/main/java/com/alibaba/otter/canal/parse/inbound/mysql/dbsync/TableMetaCache.java:134

            result.add(meta);
        }
        return result;
    }

    private LoadingCache<String, TableMeta> createLocalCache() {
        return CacheBuilder.newBuilder().build(new CacheLoader<String, TableMeta>() {

            @Override
            public TableMeta load(String name) throws Exception {
                try {
                    return getTableMetaByDB(name);
                } catch (Throwable e) {
                    // 尝试做一次retry操作
                    try {
                        connection.reconnect();
                        return getTableMetaByDB(name);
                    } catch (IOException e1) {
                        throw new CanalParseException("fetch table meta failed. table: " + name, e1);
                    }
                }
            }
        });
    }

    private TableMeta getTableMetaByDB(String fullname) throws IOException {
        boolean showCreateTable = true;
        ResultSetPacket packet = null;
        synchronized (this) {
            try {
                packet = connection.query("show create table " + fullname);
            } catch (Exception ex) {
                showCreateTable = false;
                packet = connection.query("desc " + fullname);
            }
        }
        String[] names = StringUtils.split(fullname, "`.`");

View on GitHub (pinned to 87be50e876)

Solutions

  1. Verify MySQL connectivity: test the JDBC connection with the same credentials Canal uses.
  2. Check that the canal user has SELECT privilege needed for 'show create table' on the target databases.
  3. Ensure the MySQL server is healthy and not in a recovery/failover state.
  4. If transient (during failover), Canal's outer retry loop should recover — increase connection retry settings if needed.

Example fix

# before
canal.instance.master.address=10.0.0.5:3306

# after — add connection retries and fallback
canal.instance.master.address=10.0.0.5:3306
canal.instance.master.retry.count=3
canal.instance.master.connect.timeout=10000
Defensive patterns

Strategy: retry

Validate before calling

// Before loading table meta, verify the connection is alive
try {
    mysqlConnection.query("SELECT 1");
} catch (IOException e) {
    logger.warn("Connection dead before table meta load, reconnecting");
    mysqlConnection.reconnect();
}

Try / catch

// TableMetaCache loading is internal; configure retry at the parser level:
// The cache loader already retries once. Add outer retry in the parser:
int retries = 0;
while (retries < 3) {
    try {
        TableMeta meta = tableMetaCache.getTableMeta(schema, table);
        break;
    } catch (CanalParseException e) {
        retries++;
        if (retries >= 3) throw e;
        Thread.sleep(retries * 3000L);
        connection.reconnect();
    }
}

Prevention

When it happens

Trigger: tableMetaCache.getUnchecked(fullName) triggers CacheLoader.load(), which calls getTableMetaByDB(). If that throws (connection broken, query error), the catch(Throwable) block calls connection.reconnect() and retries getTableMetaByDB(). If the retry throws IOException, the CanalParseException is thrown. This means the connection to MySQL is truly unavailable even after reconnect.

Common situations: The MySQL server is down or unreachable when Canal tries to load table metadata (common during failover). The connection pool is exhausted. A network partition separates Canal from MySQL. The canal user lacks privileges to run 'show create table' / 'desc' on the table. The table name contains special characters that break the SQL.

Related errors

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