🚨 Kafka Error Guide: 'InvalidConfigurationException: Unknown topic config name' Fix

Exact Error Message

When you create or alter a topic with a config key Kafka does not recognize, the command fails immediately:

Error while executing config command with args '--bootstrap-server localhost:9092 --entity-type topics --entity-name orders --alter --add-config retentions.ms=604800000'
java.util.concurrent.ExecutionException: org.apache.kafka.common.errors.InvalidConfigurationException: Unknown topic config name: retentions.ms
        at java.base/java.util.concurrent.CompletableFuture.reportGet(CompletableFuture.java:396)
        at java.base/java.util.concurrent.CompletableFuture.get(CompletableFuture.java:2073)
        at org.apache.kafka.common.internals.KafkaFutureImpl.get(KafkaFutureImpl.java:165)
        at kafka.admin.ConfigCommand$.alterConfig(ConfigCommand.scala:359)
Caused by: org.apache.kafka.common.errors.InvalidConfigurationException: Unknown topic config name: retentions.ms

A bad value (rather than a bad key) looks similar but names the offending property:

org.apache.kafka.common.errors.InvalidConfigurationException: Invalid value deleted for configuration cleanup.policy: String must be one of: compact, delete

What the Error Means

InvalidConfigurationException is thrown by the broker (not the client) when a configuration entry you supplied does not pass validation. Kafka keeps a strict registry of valid configuration names and their accepted value ranges, types, and enums. The admin client serializes your --add-config pairs and ships them to the controller, which validates each one against that registry before applying anything.

There are two distinct failure modes that share this exception class:

1. Unknown config name — the key is not a real Kafka config. retentions.ms (extra s), cleanup.policys, or max.message.byte are all rejected because no such property exists. Kafka does not guess your intent or fuzzy-match; an unknown name is a hard error.
2. Invalid value — the key is valid but the value fails type, range, or enum validation. cleanup.policy=deleted, retention.ms=-2, or a non-numeric string for a numeric field all fail here.

The same exception applies to both topic-level configs (set per topic) and broker-level/dynamic configs (set per broker or cluster-wide). The validation registry differs by entity type, so a name valid for a broker may be unknown for a topic.

Common Causes

1. Misspelled or pluralized config key

The single most common cause. retentions.ms instead of retention.ms, cleanup.policys instead of cleanup.policy, segments.ms instead of segment.ms, or min.insync.replica instead of min.insync.replicas. One stray character produces “Unknown topic config name”.

2. Wrong entity type for the config

Some properties exist only at the broker level and some only at the topic level. Trying to set a broker-only property such as log.retention.ms as a topic config fails — the topic-level equivalent is retention.ms. Topic configs use the short names; broker configs use the log.* prefixed names.

3. Invalid enum value

cleanup.policy accepts only delete, compact, or the combined delete,compact. Values like deleted, compaction, or none are rejected. compression.type accepts producer, gzip, snappy, lz4, zstd, or uncommitted-style typos fail.

4. Out-of-range or sentinel-mismatched numeric value

retention.ms=-1 means “retain forever” and is valid, but retention.ms=-2 is not a recognized sentinel and is rejected. min.insync.replicas=0 is below the allowed minimum. segment.bytes below 1048576 (1 MiB) is rejected on many versions.

5. Wrong type entirely

Passing a string where a number is expected (retention.ms=one-week) or a non-boolean for a boolean field (preallocate=yes instead of true) fails type coercion.

How to Reproduce the Error

Spin up a single broker and try to set a misspelled key on a topic:

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

kafka-configs.sh --bootstrap-server localhost:9092 \
  --entity-type topics --entity-name orders \
  --alter --add-config retentions.ms=604800000

The second command throws Unknown topic config name: retentions.ms. To reproduce the value variant:

kafka-configs.sh --bootstrap-server localhost:9092 \
  --entity-type topics --entity-name orders \
  --alter --add-config cleanup.policy=deleted

This throws the “Invalid value deleted for configuration cleanup.policy” form.

Diagnostic Commands

These commands are read-only and safe to run while investigating. Start by listing the topic’s current, valid configs so you can see the correct key names in context:

# Show all explicitly set and default configs for a topic
kafka-configs.sh --bootstrap-server localhost:9092 \
  --entity-type topics --entity-name orders --describe --all

# Inspect broker-level dynamic configs to confirm the right names
kafka-configs.sh --bootstrap-server localhost:9092 \
  --entity-type brokers --entity-name 1 --describe --all

# Confirm the topic exists and review its current settings
kafka-topics.sh --bootstrap-server localhost:9092 \
  --describe --topic orders

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

# Search broker logs for the exact rejected name
journalctl -u kafka --no-pager | grep -i "InvalidConfigurationException"

The --describe --all output is the authoritative list of valid keys for that entity. Compare your intended key character-for-character against what appears there.

Step-by-Step Resolution

Step 1: Identify whether it is a bad key or a bad value

Read the message. “Unknown topic config name: X” means the key X is wrong. “Invalid value Y for configuration Z” means the value Y for key Z is wrong.

Step 2: Look up the correct key name

Run the diagnostic --describe --all and find the real property. The correct retention key is retention.ms, not retentions.ms. The correct cleanup key is cleanup.policy, not cleanup.policys.

Step 3: Apply the corrected key

With the right name confirmed, run the alter with the corrected config:

kafka-configs.sh --bootstrap-server localhost:9092 \
  --entity-type topics --entity-name orders \
  --alter --add-config retention.ms=604800000

Step 4: Use a valid enum or in-range value

For cleanup.policy, use one of the accepted values. To keep both deletion and compaction, pass the combined value (quote it so the shell does not split on the comma):

kafka-configs.sh --bootstrap-server localhost:9092 \
  --entity-type topics --entity-name orders \
  --alter --add-config "cleanup.policy=delete,compact"

For infinite retention use the documented sentinel -1, not -2:

kafka-configs.sh --bootstrap-server localhost:9092 \
  --entity-type topics --entity-name orders \
  --alter --add-config retention.ms=-1

Step 5: For broker configs, target the broker entity

If the property is broker-level (for example log.cleaner.threads), set it against the broker entity, not a topic:

kafka-configs.sh --bootstrap-server localhost:9092 \
  --entity-type brokers --entity-name 1 \
  --alter --add-config log.cleaner.threads=2

Step 6: Validate the applied change

Re-run the describe to confirm the new value took and that no error was thrown:

kafka-configs.sh --bootstrap-server localhost:9092 \
  --entity-type topics --entity-name orders --describe

The corrected key should now appear in the output with your value.

Prevention and Best Practices

• Keep a vetted reference of the exact config keys your team uses (retention.ms, cleanup.policy, segment.bytes, min.insync.replicas) and copy from it rather than typing from memory.
• Store topic configuration in version control (declarative tooling such as a topics-as-code manifest) so keys and values are reviewed and validated before they reach a cluster.
• Always run kafka-configs.sh --describe --all against an existing healthy topic to see canonical names before writing new automation.
• Quote any value containing a comma, such as "cleanup.policy=delete,compact", so the shell does not mangle it.
• Validate in a staging cluster first; InvalidConfigurationException is rejected atomically, so a typo fails the whole command rather than partially applying.
• For a noisy pipeline of these failures, the free incident assistant can turn a stack trace into a likely cause. More patterns live in the Kafka guides.

Related Errors

• InvalidConfigurationException: Invalid value ... for configuration min.insync.replicas — value below the allowed minimum or above the replication factor.
• UnknownTopicOrPartitionException — the --entity-name topic does not exist; create it first or fix the name.
• ConfigException: Missing required configuration — a producer/consumer client-side config gap, distinct from broker-side topic config validation.
• PolicyViolationException — a create.topic.policy or alter.config.policy plugin rejected an otherwise-valid config.

Frequently Asked Questions

Why does Kafka reject the whole command instead of skipping the bad key?

Config changes are validated and applied atomically. If any single key or value fails validation, the controller rejects the entire request so you never end up with a partially applied configuration.

What are the valid values for cleanup.policy?

delete, compact, or the combined delete,compact. Anything else (such as deleted or compaction) throws an invalid-value error. Quote the combined form on the shell.

Is retention.ms=-1 valid?

Yes. -1 is the documented sentinel for infinite retention. Other negatives such as -2 are not recognized and are rejected.

How do I find the correct name for a config I half-remember?

Run kafka-configs.sh --describe --all against a working topic or broker. The output lists every valid property name for that entity type, which you can match against your intended key.

Does this error mean my topic was modified?

No. Because validation happens before application and is atomic, a rejected command leaves the topic exactly as it was. Re-run the corrected command once.