alibaba/canal · error · RuntimeException

unknow column : + name

Error message

unknow column :  + name

What it means

Thrown by TableMeta.getFieldMetaByName when no field in the loaded schema matches the requested column name (case-insensitive). It signals that a column referenced during row-event decoding is absent from the table metadata Canal holds, so it cannot map the binlog column to a field. A companion tryGetFieldMetaByName exists that returns null instead of throwing.

Source

Thrown at parse/src/main/java/com/alibaba/otter/canal/parse/inbound/TableMeta.java:74

        this.table = table;
    }

    public List<FieldMeta> getFields() {
        return fields;
    }

    public void setFields(List<FieldMeta> fileds) {
        this.fields = fileds;
    }

    public FieldMeta getFieldMetaByName(String name) {
        for (FieldMeta meta : fields) {
            if (meta.getColumnName().equalsIgnoreCase(name)) {
                return meta;
            }
        }

        throw new RuntimeException("unknow column : " + name);
    }

    /**
     * 尝试基于列名查找一下Filed信息,找不到时返回为null
     * 
     * @param name
     * @return
     */
    public FieldMeta tryGetFieldMetaByName(String name) {
        for (FieldMeta meta : fields) {
            if (meta.getColumnName().equalsIgnoreCase(name)) {
                return meta;
            }
        }

        return null;
    }

View on GitHub (pinned to 87be50e876)

Solutions

1. Enable and rebuild TableMeta TSDB so DDL history is tracked and the correct schema version is used per position.
2. Clear the TSDB snapshot (h2 metadata db) for the destination so meta is re-fetched from source.
3. Ensure the canal user can SELECT the current table definition and that binlogs containing the DDL are still available.
4. If calling getFieldMetaByName in custom code, prefer tryGetFieldMetaByName and handle null.

Example fix

// before (throws if column absent)
FieldMeta meta = tableMeta.getFieldMetaByName(colName);

// after (null-safe)
FieldMeta meta = tableMeta.tryGetFieldMetaByName(colName);
if (meta == null) { /* handle missing column */ }

// prefer the null-safe accessor before throwing variant
FieldMeta m = tableMeta.tryGetFieldMetaByName(name);
if (m == null) handleMissingColumn(name);

try { FieldMeta m = tableMeta.getFieldMetaByName(name); ... }
catch (RuntimeException e) {
    if (e.getMessage().startsWith("unknow column")) { /* refresh table meta / TSDB */ }
    else throw e;
}

When it happens

Trigger: getFieldMetaByName(name) iterates fields; if none equalsIgnoreCase the requested name, it throws RuntimeException. Called during event construction when Canal needs the type/charset of a column to decode the row. Occurs when the in-memory/TSDB table meta is stale relative to the binlog (DDL changed the table).

Common situations: A DDL (ADD/DROP/RENAME COLUMN) happened between the binlog position being parsed and the table meta snapshot Canal uses; TSDB not enabled or its snapshot is stale; filter references a column that no longer exists; case/quote mismatch in column naming after a rename.

Related errors

• can't find init table meta for {} with position : {}
• column size is not match for table:{},{} vs {}
• use gtid and TableMeta TSDB should be config timestamp > 0
• MySQL8.0 unmatch column metadata & pls submit issue , table
• fetch failed by table meta:{}

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