🚨 Kafka Error Guide: 'InvalidTopicException' Topic Name Is Invalid

Exact Error Message

InvalidTopicException is thrown when a topic name violates Kafka’s naming rules. Unlike a name collision, the name here would never be accepted no matter how many times you try. You will see it from kafka-topics.sh --create or from an AdminClient future:

Error while executing topic command : Topic 'my.topic_name' is invalid.
[2026-06-29 09:41:55,213] ERROR org.apache.kafka.common.errors.InvalidTopicException: Topic 'my.topic_name' is invalid.
 (kafka.admin.TopicCommand$)

From application code the wrapped form looks like this:

java.util.concurrent.ExecutionException: org.apache.kafka.common.errors.InvalidTopicException:
  Topic 'my.topic_name' collides with existing topics: [my_topic_name]
    at org.apache.kafka.common.internals.KafkaFutureImpl.wrapAndThrow(KafkaFutureImpl.java:45)
Caused by: org.apache.kafka.common.errors.InvalidTopicException:
  Topic 'my.topic_name' collides with existing topics: [my_topic_name]

The message varies with the specific rule broken. You may see is invalid, collides with existing topics, is illegal, contains a character other than ASCII alphanumerics, '.', '_' and '-', or is illegal, it can't be longer than 249 characters. All map to the same error code (INVALID_TOPIC_EXCEPTION, error 17) and the same root problem: the name itself is not allowed.

What the Error Means

Kafka enforces a strict grammar on topic names so they map cleanly onto filesystem directories, metrics, and internal bookkeeping. A topic’s log segments live in a directory named after the topic and partition, and topic names also appear in JMX metric paths. To keep both safe and unambiguous, Kafka rejects any name that breaks the rules at create time, before the topic is ever written to metadata.

The rules are: the name may contain only ASCII letters, digits, and the characters ., _, and -; it must be 1 to 249 characters long; it cannot be exactly . or ..; it cannot collide with an existing name under the metric-safe transformation; and the __ (double underscore) prefix is reserved for Kafka’s own internal topics. Break any of these and the create fails immediately. This is purely a validation failure, so no partial topic is created and there is nothing to clean up.

Common Causes

• Illegal characters. Spaces, slashes, colons, @, #, +, or non-ASCII characters are not allowed. Only a-zA-Z0-9._- are valid. A name like orders/eu or user events is rejected.
• Name too long. Kafka caps topic names at 249 characters because the on-disk directory name combines the topic, partition index, and a suffix and must fit filesystem limits. Anything over 249 fails.
• . and _ collisions. Kafka’s metrics layer replaces both . and _ with the same character, so a.b and a_b collide. Creating one when the other exists raises InvalidTopicException with the “collides with existing topics” wording, even though the raw strings differ.
• Reserved __ prefix. Names beginning with two underscores are reserved for internal topics such as __consumer_offsets and __transaction_state. A user topic like __audit is rejected to avoid clashing with Kafka internals.
• Empty name, or . / ... An empty string is not a valid name. The literal names . and .. are forbidden because they would map to the current and parent directory on disk.

How to Reproduce the Error

Attempt to create topics that break each rule in a throwaway dev cluster:

# Illegal character (slash) -> InvalidTopicException
kafka-topics.sh --bootstrap-server localhost:9092 \
  --create --topic "orders/eu" --partitions 1 --replication-factor 1

# Reserved internal prefix -> InvalidTopicException
kafka-topics.sh --bootstrap-server localhost:9092 \
  --create --topic "__audit" --partitions 1 --replication-factor 1

Each command exits non-zero with Topic '...' is invalid. To reproduce the ./_ collision, create a_b first, then attempt to create a.b: the second create fails with “collides with existing topics: [a_b]”.

Diagnostic Commands

These are read-only. The goal is to confirm the exact rule being broken and to check whether a metric-safe collision with an existing topic is the cause.

# List all topics to spot a near-duplicate that could collide
kafka-topics.sh --bootstrap-server localhost:9092 --list

# Narrow the list to names that differ only by '.' vs '_'
kafka-topics.sh --bootstrap-server localhost:9092 --list | grep -E 'a[._]b'

a_b

If a similarly named topic shows up where the only difference is . versus _, that is your collision: a.b and a_b are not allowed to coexist.

# Measure the length of a proposed name (must be 1-249)
printf '%s' "my.very.long.topic.name" | wc -c

# Describe an existing topic to confirm valid naming patterns in use
kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic orders

# Inspect any topic-level config (read-only) for a known-good name
kafka-configs.sh --bootstrap-server localhost:9092 \
  --entity-type topics --entity-name orders --describe

# Confirm the cluster is reachable and which client versions it supports
kafka-broker-api-versions.sh --bootstrap-server localhost:9092 | head -5

# Pull the broker log lines around the failed create
journalctl -u kafka --since "15 min ago" | grep -iE "invalidtopic|is invalid|collides"

The broker log echoes the precise reason, which tells you which rule to fix: an illegal-character message, a length message, a collision message, or a reserved-prefix message.

Step-by-Step Resolution

The fix is always to choose a valid name; the exception cannot be configured away. Pick the corrective action that matches the rule you broke, then issue a clean create.

1. Replace illegal characters. Restrict the name to a-zA-Z0-9._-. Convert slashes, spaces, and other separators to ., _, or -. For example, orders/eu becomes orders.eu:

   kafka-topics.sh --bootstrap-server localhost:9092 \
     --create --topic "orders.eu" --partitions 3 --replication-factor 1

2. Shorten names over 249 characters. Keep names well under the cap. A concise, hierarchical name is both valid and easier to operate. Verify length with wc -c (shown above) before creating.

3. Avoid mixing . and _. Standardize on one separator across the whole cluster. If you already use _, do not introduce a . variant of the same name (and vice versa). Pick one convention, for example all dots:

   kafka-topics.sh --bootstrap-server localhost:9092 \
     --create --topic "a.b" --partitions 3 --replication-factor 1

   If a_b already exists and you genuinely need a.b, you must rename the workload to a non-colliding name; the two cannot coexist.

4. Do not use the __ prefix. Reserve double-underscore names for Kafka internals. Rename __audit to something like audit.internal or app.audit:

   kafka-topics.sh --bootstrap-server localhost:9092 \
     --create --topic "app.audit" --partitions 3 --replication-factor 1

5. Never use empty, ., or .. names. These come from unset variables or path-joining bugs in tooling. Validate the name is non-empty and not a dot before calling create, then run the create with the corrected value.

Prevention and Best Practices

• Adopt a single naming convention up front, for example domain.entity.event using dots only, and document it so no one introduces underscore variants that collide.
• Validate topic names in your provisioning code against the regex ^[a-zA-Z0-9._-]{1,249}$ and reject the __ prefix before calling CreateTopics, so bad names fail in code review rather than at runtime.
• Never construct topic names from unsanitized user input or file paths; that is the usual source of slashes, spaces, and empty strings.
• Keep names short and human-readable; staying well under 249 characters avoids both the length cap and unwieldy on-disk directories.
• Treat the __ namespace as off-limits; if you need internal-style topics, use a clear application prefix like app. instead.
• For a quick read on which rule a failing create broke, the free incident assistant can interpret the log line and suggest a valid name.

Related Errors

• TopicExistsException — the name is valid but already taken. Distinct from InvalidTopicException, where the name would never be accepted.
• UnknownTopicOrPartitionException — a client referenced a topic that does not exist, often because a producer used a slightly different (valid) name than the one created.
• InvalidReplicationFactorException — the create failed on replication factor versus broker count, not on the name.
• InvalidConfigurationException — a topic config value (not the name) is invalid, such as an out-of-range retention setting.

Frequently Asked Questions

Which characters are actually allowed in a Kafka topic name? Only ASCII letters, digits, and the three punctuation characters ., _, and -. The name must be 1 to 249 characters and cannot be . or ... Anything else, including spaces and non-ASCII characters, triggers InvalidTopicException.

Why does a.b collide with a_b? Kafka’s metrics system maps both . and _ to the same character, so the two names are indistinguishable in metric paths. To keep metrics unambiguous, Kafka forbids names that collide under that transformation, even though the raw strings differ.

Can I create a topic that starts with __? No. The double-underscore prefix is reserved for Kafka’s internal topics like __consumer_offsets and __transaction_state. Choose an application-specific prefix instead, such as app. or audit..

Is there a workaround to allow a longer name or special characters? No. These limits are enforced by the broker because topic names map to on-disk directories and metric paths. The only fix is to choose a compliant name. See more Kafka guides for naming conventions that scale.