What causes UnknownTopologyException?

Referencing a NamedTopology by a name that was never added via `KafkaStreamsNamedTopologyWrapper.addNamedTopology(...)` (typo or wrong name passed to lookup/removeNamedTopology). Looking up or removing a NamedTopology that has already been removed, or that exists on some clients but not the one being called (each instance must be told about add/remove independently — the call is not fully async/global). Race during a rolling add/remove of named topologies: a query or task lookup arrives at an instance before its `addNamedTopology(...)` completed, so that instance does not yet know the topology. Using the experimental, internal `org.apache.kafka.streams.processor.internals.namedtopology` API (multiple independent topologies in one app) at all — it never got a finalized public KIP, so the exception is an internal-only signal that a named topology isn't present on this client.

How do I fix UnknownTopologyException?

Add the NamedTopology on every running instance before referencing it: call `addNamedTopology(NamedTopology)` on each client (it is not purely async) and wait for completion before issuing lookups/queries against that name. Only `removeNamedTopology(name)` (and `cleanUpNamedTopology(name)`) for topologies that are actually present, and propagate the removal to all instances so no client looks up a name another already dropped. Treat NamedTopologies as experimental/internal and avoid them in production: the public KIP was abandoned (KAFKA-13282 'Won't Fix'), the API lives in an `internals` package with no compatibility guarantees, and may change or be removed — prefer one topology per app, or separate applications, for isolation. If you must use it, verify the active set via the wrapper's accessors (e.g. getTopologyByName/allNamedTopologies) before lookup, and gate queries on the topology being known on the local client to avoid the exception.

Is UnknownTopologyException retriable?

No — UnknownTopologyException is not retriable. Retrying the same call will not help; the underlying cause must be fixed first.

Kafka Exception `UnknownTopologyException`

org.apache.kafka.streams.errors.UnknownTopologyException

Non-retriable Streams

Indicates that the NamedTopology being looked up does not exist in this application

Common Causes

Referencing a NamedTopology by a name that was never added via `KafkaStreamsNamedTopologyWrapper.addNamedTopology(...)` (typo or wrong name passed to lookup/removeNamedTopology).
Looking up or removing a NamedTopology that has already been removed, or that exists on some clients but not the one being called (each instance must be told about add/remove independently — the call is not fully async/global).
Race during a rolling add/remove of named topologies: a query or task lookup arrives at an instance before its `addNamedTopology(...)` completed, so that instance does not yet know the topology.
Using the experimental, internal `org.apache.kafka.streams.processor.internals.namedtopology` API (multiple independent topologies in one app) at all — it never got a finalized public KIP, so the exception is an internal-only signal that a named topology isn't present on this client.

Solutions

Add the NamedTopology on every running instance before referencing it: call `addNamedTopology(NamedTopology)` on each client (it is not purely async) and wait for completion before issuing lookups/queries against that name.
Only `removeNamedTopology(name)` (and `cleanUpNamedTopology(name)`) for topologies that are actually present, and propagate the removal to all instances so no client looks up a name another already dropped.
Treat NamedTopologies as experimental/internal and avoid them in production: the public KIP was abandoned (KAFKA-13282 'Won't Fix'), the API lives in an `internals` package with no compatibility guarantees, and may change or be removed — prefer one topology per app, or separate applications, for isolation.
If you must use it, verify the active set via the wrapper's accessors (e.g. getTopologyByName/allNamedTopologies) before lookup, and gate queries on the topology being known on the local client to avoid the exception.

Example Stack Trace

org.apache.kafka.streams.errors.UnknownTopologyException: Unable to locate topology named-topology-orders in the application
	at org.apache.kafka.streams.processor.internals.TopologyMetadata.lookupBuilderForNamedTopology(TopologyMetadata.java:561)
	at org.apache.kafka.streams.processor.internals.namedtopology.KafkaStreamsNamedTopologyWrapper.removeNamedTopology(KafkaStreamsNamedTopologyWrapper.java:214)
	at com.example.NamedTopologyManager.remove(NamedTopologyManager.java:73)

Diagnostic Commands

# Before lookup/removeNamedTopology, verify the name is present on THIS client via the wrapper accessors (getTopologyByName / allNamedTopologies); the NamedTopology API is experimental/internal (KAFKA-13282, Won't Fix).

Hitting UnknownTopologyException in production? Conduktor Console gives you real-time visibility into clients, consumer groups, and broker health. Browse every Kafka exception or protocol error code.

Kafka Exception UnknownTopologyException

Common Causes

Solutions

Example Stack Trace

Diagnostic Commands

Related

Kafka Exception `UnknownTopologyException`