> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nx1cloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot common Debezium server issues

> Troubleshooting guide for common issues when running Debezium Server.

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

<Note>
  The default `initial` snapshot mode works well for most use cases.
  Modifications to snapshot behavior require platform configuration changes.
</Note>

## 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

* To get an overview of Debezium, refer to the [Debezium in NexusOne](./debezium-server-in-nx1) page.
* To learn about best practices when using Debezium, refer to the
  [Debezium best practices](./debezium-server-best-practices) page.
* For more details, refer to the official [Debezium documentation](https://debezium.io/documentation/)
  and [Apache Iceberg documentation](https://iceberg.apache.org/docs/latest/). The Debezium community
  also provides an extensive guide on
  [source connector configurations](https://debezium.io/documentation/reference/stable/connectors/index.html).
* If you are using the NexusOne portal and want to learn how to use the Debezium server, refer to the
  [Ingest](/documentation/data-pipeline/overview/ingest) page.