Debezium Won't Start? The Whitespace Bug That Stumped Our Client
We recently got a support ticket that looked simple at first. A client's Debezium MySQL connector kept failing at startup. The error pointed to message.key.columns. The config looked reasonable. But nothing worked.
Here's what happened — and how we fixed it without touching the database schema.
The Problem
The client had a MySQL table with a space in its name: dbo.Sourcing Id Master.
They configured the connector like this:
"message.key.columns": "dbo.Sourcing Id Master:id"
Connector validation failed immediately. They tried escaping — backslashes, quotes, every combination. Same error every time.
Why Escaping Doesn't Work Here
The problem isn't at runtime. It's at config validation time.
Debezium's validator for message.key.columns requires the fully-qualified table identifier to contain no whitespace. The validator rejects it before the connector even connects to MySQL. No escaping fixes this.
The Fix
Step 1 — capture the table via table.include.list (accepts spaces fine):
"table.include.list": "dbo\.Sourcing Id Master"
Step 2 — build the message key with a ValueToKey SMT:
"transforms": "ValueToKey",
"transforms.ValueToKey.type": "org.apache.kafka.connect.transforms.ValueToKey",
"transforms.ValueToKey.fields": "id"
Debezium includes primary key fields in the record value anyway — the SMT pulls id from there and sets it as the Kafka message key, bypassing the validator entirely.
Result
Connector starts. Table captured. Keys work. Zero schema changes.
At Hossted, we help enterprises run open source in production — Kafka, Debezium, PostgreSQL, Kubernetes and more. Follow us on LinkedIn for more cases like this.
Top comments (3)
This is a perfect example of why infrastructure-as-code and configuration management can be so finicky—sometimes the most complex system failures come down to a single invisible character. As someone who spends a lot of time in "failed-to-fixed" playbooks, I really appreciate you documenting these obscure edge cases to save the rest of us hours of debugging!
Thank you! Exactly — invisible character bugs are the worst kind. They look perfectly fine on screen but silently break everything at validation.
Absolutely. It’s a classic 'Linter vs. Reality' scenario! In DevSecOps, we often say that if a human can't see the bug, the pipeline should. This is a great reminder for all of us to bake more robust schema validation and 'invisible character' linting into our CI stages before the config even hits the container. Thanks again for sharing this 'war story'—it’s these specific playbooks that help us build more resilient systems!