> For the complete documentation index, see [llms.txt](https://docs.lenses.io/latest/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lenses.io/latest/k2k/configuration-reference/troubleshooting.md).

# Troubleshooting

Diagnose runtime replication issues.

This page covers symptoms that appear after K2K has started. For pre-flight connectivity checks, see [Startup validation](https://docs.lenses.io/latest/k2k/configuration-reference/startup-validation.md). For a structured pre-deployment workflow, see the [Validation checklist](https://docs.lenses.io/latest/k2k/runbooks/validation-checklist.md).

## Replication lag growing

| Symptom                         | Likely cause                              | What to check                                                                                                                                                                                                                        |
| ------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Lag metrics increase steadily   | Insufficient throughput for source volume | [Replication performance tuning](https://docs.lenses.io/latest/k2k/configuration-reference/replication-performance-tuning.md), [Horizontal scaling](https://docs.lenses.io/latest/k2k/configuration-reference/horizontal-scaling.md) |
| Lag spikes during rebalances    | Consumer group instability on source      | K2K group configuration in [Consumer group](https://docs.lenses.io/latest/k2k/configuration-reference/consumer-group.md); partition count vs instance count                                                                          |
| Lag on specific partitions only | Hot partitions or assignment skew         | Partition distribution across replicator instances; [Observability](https://docs.lenses.io/latest/k2k/configuration-reference/observability.md) metrics                                                                              |

## Offset mapping not progressing

| Symptom                                    | Likely cause                                                                                          | What to check                                                                                                                                                                                                             |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Target consumer groups stay at old offsets | Offset mapper not running                                                                             | [Deployment](https://docs.lenses.io/latest/k2k/deployment.md#offset-mapping-both-applications-required) — both `k2k` and `k2k-offset-mapping` must run                                                                    |
| No mappings available                      | Replicator not running with offset mapping enabled                                                    | `features.offsetMapping: enabled` in pipeline; replicator must record mappings                                                                                                                                            |
| Groups not translated                      | Group not matched by `groups.consumerGroups`                                                          | [Offset mapping](https://docs.lenses.io/latest/k2k/configuration-reference/offset-mapping.md#polling-and-group-selection) — the filter is a regex *or* an exact list                                                      |
| Translations skipped with no error         | `features.applyMappingsGuard` (on by default) found a newer committed offset on the target            | [Mappings guard](https://docs.lenses.io/latest/k2k/configuration-reference/offset-mapping.md#mappings-guard)                                                                                                              |
| Offset mapper fails at startup             | Missing `target.kafka.consumer."group.id"`, or a license token without the offset mapping entitlement | [Offset mapping](https://docs.lenses.io/latest/k2k/configuration-reference/offset-mapping.md#prerequisites), [Licensed features](https://docs.lenses.io/latest/k2k/configuration-reference/licenses.md#licensed-features) |

Use [k2k-tool](https://docs.lenses.io/latest/k2k/k2k-standalone-tool.md) to inspect committed offsets during failover or migration cutover.

## Control topic errors

K2K uses internal control topics on the target Kafka cluster for coordination, commits, offset mappings, and metrics. See the [Glossary](https://docs.lenses.io/latest/k2k/glossary.md#coordination) for definitions.

| Symptom                                         | Likely cause                                  | What to check                                                                                                                                                                                                    |
| ----------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Startup fails on control topic validation       | Topic misconfiguration or missing permissions | [Topic creation](https://docs.lenses.io/latest/k2k/configuration-reference/topic-creation.md), [Security and permissions](https://docs.lenses.io/latest/k2k/configuration-reference/security-and-permissions.md) |
| `onControlMessageDeserializationError` warnings | Corrupted or incompatible control messages    | [Pipeline tuning](https://docs.lenses.io/latest/k2k/configuration-reference/pipeline-tuning.md) error handling settings                                                                                          |
| Replication stalls after rebalance              | Exclusive assignment not granted              | [Horizontal scaling](https://docs.lenses.io/latest/k2k/configuration-reference/horizontal-scaling.md); check control topic consumer lag                                                                          |

Do not delete control topics while K2K is running. If control topics are lost, stop K2K, recreate them (or enable auto-creation), and restart. Replication may need to resume from the last committed offset.

## Connection and auth failures at runtime

| Symptom                         | Likely cause                           | What to check                                                                                                                                                                                                                                        |
| ------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Intermittent `TimeoutException` | Network latency to target cluster      | Deploy replicator near the target cluster; see [Deployment](https://docs.lenses.io/latest/k2k/deployment.md#deployment-recommendation)                                                                                                               |
| SASL authentication errors      | Expired credentials or wrong mechanism | [Kafka connectivity and authentication](https://docs.lenses.io/latest/k2k/configuration-reference/kafka-connectivity-authentication.md), [Secrets and templates](https://docs.lenses.io/latest/k2k/configuration-reference/secrets-and-templates.md) |
| Schema Registry errors          | Registry unreachable or auth mismatch  | [Schema Registry connectivity and authentication](https://docs.lenses.io/latest/k2k/configuration-reference/schema-registry-connectivity-authentication.md)                                                                                          |

Enable `features.checkKafkaConnectionOnStartup` temporarily after credential or network changes. See [Startup validation](https://docs.lenses.io/latest/k2k/configuration-reference/startup-validation.md).

## Licensing failures

| Symptom                                                                | Likely cause                                                                        | What to check                                                                                                                                                                              |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Pipeline ran fine, then stopped with a free tier partition limit error | No `license.token`, and a new topic pushed the matched partition total over the cap | [Free tier](https://docs.lenses.io/latest/k2k/configuration-reference/licenses.md#free-tier) — the cap is re-checked on every rebalance, so a topic regex can exceed it long after startup |
| A feature fails at startup with a license restriction                  | Token does not carry that entitlement                                               | [Licensed features](https://docs.lenses.io/latest/k2k/configuration-reference/licenses.md#licensed-features)                                                                               |
| Running pipeline stops unexpectedly                                    | License expired — expiry is checked continuously, not only at startup               | [Expiry](https://docs.lenses.io/latest/k2k/configuration-reference/licenses.md#expiry)                                                                                                     |
| Startup fails on EULA                                                  | `license.acceptEula` not set to `true`                                              | [License](https://docs.lenses.io/latest/k2k/configuration-reference/licenses.md)                                                                                                           |

## Exactly once and duplicate records

| Symptom                     | Likely cause                                 | What to check                                                                                                                                                                                            |
| --------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Duplicate records on target | Exactly once not enabled or fencing failure  | [Exactly once delivery](https://docs.lenses.io/latest/k2k/configuration-reference/exactly-once-delivery.md), [Commit tuning](https://docs.lenses.io/latest/k2k/configuration-reference/commit-tuning.md) |
| Producer transaction errors | Target cluster does not support transactions | Cluster compatibility in [Releases and compatibility](https://docs.lenses.io/latest/k2k/deployment/releases-and-compatibility.md)                                                                        |

## Getting help

When reporting an issue, include:

* K2K version (`k2k --version`)
* Pipeline name and relevant feature toggles (redact secrets)
* Metrics or logs from [Observability](https://docs.lenses.io/latest/k2k/configuration-reference/observability.md) exporters
* Output of `k2k-tool describe` if offset-related

Feedback channels are listed on the [home page](https://docs.lenses.io/latest/k2k/readme.md#feedback).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.lenses.io/latest/k2k/configuration-reference/troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
