What you might see
You may see: `cdc_binlog_required_but_unavailable`, `failed to read source binlog position`, CDC stream startup failure, or a stream that immediately fails before any events are applied.
Error Codes In Plain English
cdc_binlog_required_but_unavailable: failed to read source binlog position
failed_to_read_source_binlog_position: failed to read source binlog position
Why it usually happens
- Binary logging is not enabled on the source database.
- The source user does not have replication/binlog privileges.
- Managed database parameter groups were changed but the database was not restarted.
- The source is using a binlog format that is not compatible with row-level CDC.
- The source connection points at a read replica or proxy that does not expose binlog position.
- MariaDB/MySQL version differences require checking a different status command.
How to fix it
1. Confirm binary logging is enabled on the source.
2. Confirm the source user has replication privileges.
3. Confirm `binlog_format` is `ROW`.
4. Restart the database if binlog settings were changed in a parameter group.
5. Re-validate the source connection in Cupcake.
6. Start the CDC stream again.
Typical MySQL grants:
```sql
GRANT REPLICATION CLIENT, REPLICATION SLAVE ON *.* TO 'cupcake_user'@'%';
FLUSH PRIVILEGES;
```
For MySQL 8.0.23+, `REPLICATION SLAVE` may be shown as `REPLICATION REPLICA` depending on tooling/version.
How to avoid it next time
When onboarding a source database for CDC, make binlog checks part of the preflight checklist. Keep a dedicated Cupcake source user with replication read permissions and avoid using application users for CDC.
SQL to check
```sql
SHOW VARIABLES LIKE 'log_bin';
SHOW VARIABLES LIKE 'binlog_format';
SHOW MASTER STATUS;
SHOW GRANTS FOR CURRENT_USER();
```
For newer MySQL:
```sql
SHOW BINARY LOG STATUS;
```
Expected basics:
- `log_bin` should be `ON`.
- `binlog_format` should be `ROW`.
- binlog status should return a file and position.