## TL;DR
A Debezium connector stuck in a non-running state is usually blocked on the source database: waiting on a log position, blocked by a long transaction, or failing to snapshot a huge table. Check the connector tasks and the source database state, wait bounded only for genuine snapshot progress, and escalate with the block named. CDC stalls are database stories, not connector stories.

```text
agent timed out waiting for debezium connector status, connector stuck
```

## Use this when
- An agent waits on a Debezium connector that never reaches running.
- Connector tasks show no progress.
- The agent's timeout fires first.

## Not for this skill when
- The connector fails fast with an error. Read the error.
- The connector runs but lags. That is a throughput question.

## Steps
1. Query the connector and task states via the Connect REST API. Note the states. Verify: the stall point is named
2. Check the source database: long-running transactions, log retention, and lock contention. Note the database state. Verify: the database side is inspected
3. If snapshotting, check snapshot progress: tables done versus remaining. Note the progress. Verify: snapshot progress is measured
4. Wait a bounded time for genuine progress; escalate on no progress. Note the deadline. Verify: waiting is bounded
5. Escalate with connector state, task states, and database findings. Note the escalation. Verify: a human gets the full picture

## Variant phrasings
### debezium connector stuck not running
The symptom phrasing.
### debezium snapshot taking forever
The snapshot-shaped search.

Compatibility: Debezium on Kafka Connect. Status via the Connect REST API; database specifics vary by source.

## Why it happens
Debezium reads the database's transaction log, which ties the connector's progress to the database's state: a long transaction holds the log position, aggressive log retention deletes what the connector has not read yet, and initial snapshots of huge tables take hours honestly. The connector status reflects all of that as stuck. Agents that only watch the connector miss that the database is the actual system to investigate.

## Edge cases / pitfalls
- Restarting a stuck connector during a snapshot restarts the snapshot. Prefer patience over restarts when progress is real.
- Log retention shorter than the connector's lag deletes unprocessed history permanently. Size retention for worst-case lag.
- A connector that the agent restarts in a loop during an outage never makes progress. Back off between restarts.
- Schema history topic problems can wedge the connector without touching the data path. Check the schema history topic too.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_xKwLHF9moQQJw3Xy0b3DVA