# Troubleshooting — the errors this stack actually hands you

Every section below was written against the real configuration of the lab
(broker listeners, ports, and versions as shipped). Work top to bottom; the
commands named in each fix are read-only unless marked.

## §1 — Nothing connects: `Connection refused` / producer hangs

**Symptom:** `scripts/up.sh` hangs at "Waiting for the KRaft quorum…", or
any client says `Connection to localhost:9092 failed`.

**What it almost always is: `LAB_HOST_IP` (in `kafka-lab/docker/.env`).**
The brokers **advertise** the address in that file; clients learn it from
broker metadata even if your first connection succeeded. If Docker runs on
your own machine it must be `localhost`; a remote Docker daemon needs that
host's address.

```bash
# read-only checks
cat kafka-lab/docker/.env                    # what are the brokers advertising?
docker compose -f kafka-lab/docker/docker-compose.yml ps   # are the 3 brokers Up (healthy)?
docker exec kafka-1 /opt/kafka/bin/kafka-topics.sh --bootstrap-server kafka-1:29092 --list
```

If the last command lists topics, the cluster is fine and the problem is
**only** the advertised address. Fix `.env`, then restart the brokers so
they advertise the new address (`docker compose … up -d` re-creates them).

**Second suspect: port 9092 already taken** on the Docker host (another
Kafka, another lab). `docker ps` shows a published `9092->`; free it or
re-map the lab's ports (not needed for anything else in this course).

## §2 — The consumer prints nothing (and it's not a bug)

Fresh group + no `--from-beginning` = starts at `latest` = nothing until
new records arrive. Same group *with* the flag = still nothing, because the
group already committed an offset (Exercise 01's whole point). Before
debugging anything, look at the group's ledger:

```bash
scripts/k kafka-consumer-groups.sh --describe --group <your-group>
# CURRENT-OFFSET vs LOG-END-OFFSET tells you where the group actually is
```

A new group id (`--group course.debug-1`) removes all memory and reads
from scratch — the fastest "is anything on the topic?" test.

## §3 — `--property print.partition=true` shows no partition column

Property names are exact. It works on `kafka-console-consumer.sh` only
(Kafka 3.9), and only with the value `true` — e.g.
`--property print.partition=true`. If you typed `print.partition` bare or
on the producer, the CLI ignores it silently. Test with
`--max-messages 1` to keep the read bounded.

## §4 — `scripts/run.sh` / `run-spring.sh` fails to compile

The lab compiles with `--release 25`. Check what you're actually running:

```bash
java -version          # needs 25.x
./mvnw -version        # wrapper works without a global Maven
```

`UnsupportedClassVersionError` at runtime = an older JDK compiled it —
re-run `./mvnw -q clean compile` under JDK 25. JAVA_HOME pointing at an
old JDK is the usual culprit.

## §5 — Terminal A freezes when Terminal B dies (Exercise 03)

Not a hang: the **rebalancing** group pauses every member for a few
seconds. If it *stays* frozen, the two consumers were started with
different `--group` ids (they never shared — check the exact command), or
the survivor's `--timeout-ms` expired. Re-run the pair with a fresh group
id and a longer `--timeout-ms`.

## §6 — `run-spring.sh` says the port is busy, or a Ctrl-C'd app lingers

The script auto-picks a free port (8082, then 18080) via `lsof`. If both
are taken, or an earlier run didn't die cleanly:

```bash
lsof -nP -iTCP:8082 -sTCP:LISTEN     # who holds it?
kill <PID>                           # your own stray spring-lab process
```

Never needed: touching Docker volumes for this.

## §7 — DLT shows more records than your run produced

Topics **retain history** (Exercise 01). If you re-run exercises, the DLTs
accumulate poison records from every previous run. Match counts to your
run's timestamps, or bound reads with `--max-messages`. For a truly fresh
cluster, the reset warning in `SETUP.md` is the (only) sanctioned way.

## Still stuck?

- Re-read the exercise's Hints section, then `agent-guide/PROMPTS.md` — a
  coding agent with your *actual terminal output* is exactly what the
  diagnostic prompt in that file is for.
- Official references: Kafka configuration docs
  (kafka.apache.org/documentation) for every knob named here; Spring Kafka
  reference (docs.spring.io/spring-kafka) for the listener/retry machinery
  in Exercises 04–05.
