Skip to main content
There are common problems encountered when running the Debezium server. This troubleshooting page describes the resolutions to these common problems.

​
Source database connection issues

  • Problem: The connector fails to connect to the source database.
  • User actions:
    • Verify database hostname and port are correct in your portal configuration.
    • Confirm that the source database credentials have appropriate permissions.
    • Ensure the database is properly configured for Change Data Capture (CDC):
      • PostgreSQL: wal_level=logical, replication slot created
      • SQL Server: CDC enabled at database and table levels
      • MySQL: Binary logging enabled with ROW format
      • Oracle: Supplemental logging enabled
    • Review connector logs available through the NexusOne portal for specific connection errors.
  • Platform support: Contact the NexusOne support team to review network connectivity and connector status if the connection issues persist after verifying source configuration.

​
Source database permission issues

  • Problem: The connector connects but fails to read change events or access the source tables.
  • User actions:
    • Review the database-specific permission requirements in the source setup section
    • Verify the Debezium user has:
      • Replication permissions for PostgreSQL and MySQL
      • CDC read permissions for SQL Server
      • LogMiner access for Oracle
      • SELECT permissions on captured tables
    • Check that privileges aren’t revoked after initial setup
    • Test permissions by manually querying CDC structures with the Debezium user
  • Platform support: Contact the NexusOne support team if the permission grants appear correct but the issues persist.

​
Replication lag

  • Problem: CDC pipeline falls behind source database changes
  • User actions:
    • Review and optimize table filters to capture only necessary tables.
    • Monitor source database transaction log generation rate.
    • Consider scheduling large batch operations during off-peak hours.
    • Reduce transaction log retention if the generated volumes are very high.
  • Platform support: If replication lag persists with optimized filters, do the following:
    • Contact the NexusOne support team to discuss resource allocation adjustments for your instance.
    • For very high-volume sources, discuss scaling options or batch size optimization.

​
Schema evolution conflicts

  • Problem: Source schema changes cause pipeline failures or data inconsistencies
  • User actions:
    • Understand that debezium.sink.iceberg.allow-field-addition defaults to false.
    • Test all schema changes in a non-production environment first.
    • Plan schema modifications with awareness of current schema evolution settings.
    • Avoid incompatible type changes. For example, changing a string column to an integer.
  • Platform support: If you need to enable schema evolution:
    • Contact the NexusOne support team to request the allow-field-addition=true configuration and provide guidance on managing schema changes.
    • Discuss your specific schema evolution requirements and use case.
  • Workarounds: For urgent schema changes without schema evolution enabled:
    • Add new columns. You may not be able to capture new fields.
    • Avoid renaming or dropping columns while an active CDC is in progress.
    • Consider redeploying the connector after significant schema changes.

​
Initial snapshot issues

  • Problem: The initial snapshot times out, fails to complete, or impacts the source database’s performance.
  • User actions:
    • Schedule initial deployment during database off-peak hours
    • Monitor source database load during snapshot process
    • Ensure adequate connection pool capacity on the source database
    • Verify network stability between source and NexusOne
  • Platform support: For large tables or persistent snapshot issues, do the following:
    • Contact NexusOne support to discuss incremental snapshot options or other snapshot-related configurations
    • For multi-terabyte tables, discuss alternative snapshot strategies or backfill approaches
    • Platform monitoring can identify if timeouts are occurring at the connector level
The default initial snapshot mode works well for most use cases. Modifications to snapshot behavior require platform configuration changes.

​
Data inconsistency or missing changes

  • Problem: You made some changes, but they appear to be missing in the Iceberg lakehouse.
  • User actions:
    • Verify table filters include all intended tables.
    • Check that you enabled the source database CDC for all captured tables.
    • Ensure the source database commits transactions. Uncommitted changes aren’t captured.
    • Review the source database CDC logs for any gaps or errors.
  • Platform support: If the source database configuration is correct, but data inconsistencies persist, do the following:
    • Contact the NexusOne support team to review connector offsets and checkpointing. They can also verify Iceberg sink processing and investigate potential issues in the CDC pipeline.
    • Provide specific examples of missing data, including timestamps and table names.

​
Additional resources