Skip to main content

Kafka troubleshooting and operations

Use this guide for a prepared backend/KafkaTester environment. Read settings and prerequisites before changing credentials or topology. Preserve topic data, partition assignments, and consumer offsets during diagnosis.

1. Native ABI mismatch​

ERR_DLOPEN_FAILED or NODE_MODULE_VERSION ... usually means a native module was built for a different Node major. Backend requires Node 22 or newer. Install and run with the same selected version.

From the backend directory, reinstall with the trusted lockfile, or rebuild native dependencies:

pnpm install --trust-lockfile
pnpm kafka:rebuild-native

The install script rebuilds Kafka native dependencies and attempts better-sqlite3 rebuilding. Do not copy another Node version's node_modules.

2. Corepack signature error​

For Cannot find matching keyid, inspect the installed Corepack/pnpm setup. The repository pins pnpm 10.27.0. Where the installed Corepack supports this route:

corepack enable
corepack prepare pnpm@10.27.0 --activate
pnpm -v

Then repeat the dependency install. A separately installed pnpm of the pinned version is another supported package-manager route. Do not copy another developer's absolute binary path.

3. Service starts but processes no events​

Check the selected environment, application/admin roles, topic names in KafkaTopics, consumer group, and partition-assignment logs. All advertised broker endpoints must be reachable, not only the bootstrap port. Unified runtime reads root settings. Standalone workers use their own entrypoint configuration.

4. Outbox does not publish​

Inspect OutboxEvent.status, dispatcher logs, and producer errors. In split exercises, confirm pnpm kafka:kt:outbox:watch runs.

PREQUEUED needs explicit release. PENDING needs a dispatcher. DISPATCHING can await publication acknowledgment or recovery. Stale recovery probes broker state before requeue/marking. Do not assume a timeout means the event was never published.

See outbox behavior for states and recovery boundaries.

5. Invalid status transitions​

Preserve exact errors when reporting them:

Érvénytelen outbox státuszváltás: SUCCESS -> PUBLISHED
Érvénytelen outbox státuszváltás: PUSHED_FAILURE -> PUBLISHED
Érvénytelen outbox státuszváltás: SUCCESS -> PUSHED_FAILURE

Check for unintended all-in-one plus split-runtime overlap. Run one intended topology. The current publisher uses atomic DISPATCHING claims and compare-and-set completion. Consumers skip terminal work. Inspect that path instead of forcing terminal rows backward.

6. Consumer distribution differs from expectation​

Members of the same group share partitions. Different groups read independently. Check group names and partition count before treating an idle member as failed.

7. Operational checks​

Keep an explicit topic configuration policy for replication, retention, and access control. Monitor consumer lag, dead-letter traffic, outbox backlog, and rebalance logs. Keep a consistent Node major for native modules.

A successful connection does not prove ordering, processing, or provider confirmation. Check the affected business result. Delete/recreate and eraser commands are destructive maintenance, not routine connection diagnostics.