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

# Troubleshooting

> Symptom-first answers: startup failures, missing menu areas, short fetches, stuck or failed streams, and login errors.

Symptom-first, most common first. Every behaviour here is deliberate — the fix
is usually one property or one concept, not a bug report. If your symptom
isn't listed, ask in
[Discussions](https://github.com/alginte/community/discussions).

## The app exits immediately at startup

The log ends with:

```
Kafka is unreachable at startup: ... Start the broker, fix
spring.kafka.bootstrap-servers, or set
alginte.startup-connectivity-check.enabled=false to skip this check.
```

Alginte **fails fast by design** when the broker is unreachable — a clear
startup error instead of a UI where every page times out. Almost always one
of:

* **Wrong address for the container's point of view.** Inside Docker,
  `localhost:9092` is the *container*, not your machine. Use a
  hostname reachable from the container, or join the broker's Docker network —
  see [Run with Docker](/installation/docker).
* **The broker isn't up yet.** In compose files, order the app after the
  broker with a healthcheck (`depends_on: condition: service_healthy`) — the
  [playground compose](/installation/playground) shows the pattern.
* No broker at all? The [playground](/installation/playground) bundles one.

The escape hatch (`alginte.startup-connectivity-check.enabled=false`) skips
the check entirely; the app starts regardless and connects once the broker
appears — use it when the broker is expected to come up later.

## An area is missing from the menu

**Kafka Connect, Schema Registry, or ksqlDB don't appear in the sidebar.**
Their menu areas show only when the matching URL is configured
(`ALGINTE_CONNECT_URL`, `ALGINTE_SCHEMAREGISTRY_URL`, `ALGINTE_KSQLDB_URL`) —
an unconfigured integration is hidden rather than shown broken. Wire them up
in [Configuration](/operate/configuration).

If the URL *is* set but the service is down, the area stays visible and
degrades; the service-health indicator in the sidebar footer shows which
upstream is unreachable.

## Messages: fewer records than requested

Two different causes, distinguished by the note above the table:

* **"Incomplete data polled"** (warning) — the polling budget ran out before
  the fetch filled. Raise `alginte.consumeMaxPollAttempts` (default 40) for
  slow brokers or very large records. The read was genuinely cut short.
* **Compacted topic** (info, from **0.7.0**) — nothing was cut short: on a
  [compacted topic](/guides/messages#compacted-topics-show-fewer-records-than-you-asked-for)
  offset ranges contain gaps, so the range simply held fewer live records
  than its size suggests. Blank value cells there are *tombstones* (real
  records marking a key deleted), not decoding failures.

## A stream shows ERROR (or won't leave REBALANCING)

From **0.7.0**: a stream whose processing threads have died shows **ERROR** —
most commonly a **source topic deleted after deploy**, which Kafka Streams
cannot recover from. Recreate the topic (or fix the design) and
**Stop**/**Start** the stream — details in
[Deploy & manage](/streams/deploy#when-a-stream-shows-error). Deploying
against a topic that doesn't exist is blocked at Submit with a message naming
it.

On **0.6.0 and earlier**, that same dead-thread condition displays as
`REBALANCING` indefinitely — if a stream rebalances forever, check the server
log for `MissingSourceTopicException`.

## OIDC sign-in is rejected with `license_required`

Single-sign-on is a PRO feature; a Community instance rejects OIDC sign-in
with `license_required`. Community's built-in login is the
[single-account option](/operate/authentication). Full matrix on
[Editions & licensing](/editions/licensing); OIDC specifics (including the
allowlist fail-fast at startup) on [OIDC setup](/operate/oidc-setup).

## Port 8888 is already taken

Another process (Jupyter is the classic) holds the port. For the playground:
`ALGINTE_PORT=8890 docker compose up -d`. For your own `docker run`, change
the host side of the mapping: `-p 9000:8888`.

## Still stuck?

Open a [Discussion](https://github.com/alginte/community/discussions) or an
[Issue](https://github.com/alginte/community/issues/new/choose) — include the
Alginte version (About page), broker distribution/version, and the relevant
log lines.