Troubleshooting Kafka Writer

Failed to parse Connection Retry Policy: Invalid key '<Key>'

The Connection Retry Policy contains an unrecognized key.

Use only valid keys: initialRetryDelay, retryDelayMultiplier, maxRetryDelay, maxAttempts, totalTimeout. Format: Key=Value;Key=Value.

Connection Retry Policy '<key>' must be a valid time value

Value for a time-based parameter is not in valid format.

Use numeric milliseconds (5000) or time units (5s, 5m, 1h). No spaces between number and unit.

Provide the Topics in this format: source,TopicName;

Topics property syntax is incorrect.

Single topic: use topic name only. Multiple: 'source,TopicName;source2,TopicName2'. Semicolons separate mappings; comma separates source from topic.

Topic Key is not supported with single topic name

TopicKey set but Topics contains only a single topic name.

Remove TopicKey when using a single topic. Use topic mapping format if routing is needed.

Topic Key is mandatory when using multiple topics

Topics has multiple mappings but TopicKey is not specified.

Set TopicKey to specify the routing field. Examples: @metadata(TableName) for CDC, field name for typed events.

DataTopicConfig must be in valid JSON format

DataTopicConfig contains invalid JSON syntax.

Ensure valid JSON with double quotes for keys/strings. Example: {"PartitionCount":1,"ReplicationFactor":1}.

CommitPolicy format invalid

CommitPolicy is not in EventCount=<n>;Interval=<duration> format.

Example: EventCount=1000;Interval=5m. Semicolon separates parameters; = separates key from value.

Custom Partition Key must contain non-empty values

CustomPartitionKey has empty values between semicolons.

Use format: field1;field2;field3. Remove trailing/leading semicolons and empty values.

Custom Message Key cannot be empty when MessageKey=Custom

MessageKey is Custom but CustomMessageKey is empty.

Configure CustomMessageKey with key=value pairs. Example: id=customerId;name=customerName.

Timed out waiting for node assignment. Call: listTopics

Kafka AdminClient cannot connect to broker cluster. Broker addresses incorrect, network latency, firewall blocking, or brokers down.

Verify Broker Address is correct and reachable. Ensure firewall allows outbound connections to Kafka ports. Confirm brokers are running.

Unexpected authentication error

Schema Registry URL is unreachable (wrong host/port, HTTP vs HTTPS mismatch, DNS/firewall/VPC).

Ensure the URL in the Connection Profile is valid and reachable. Verify the Schema Registry is running.

Metadata/Userdata field not found: key <keyName>

A @metadata() or @userdata() key in TopicKey, PartitionKey, MessageKey, or MessageHeader does not exist in the incoming event.

Verify the field exists in the WAEvent metadata or userdata. Check spelling (case-sensitive).

Topic <TopicName> does not exist and auto-create is disabled

The topic does not exist and AutoCreateTopic is false. Or user lacks DESCRIBE permission.

Set AutoCreateTopic=true, or manually create the topic. Ensure DESCRIBE ACL is granted on the topic.

Cluster authorization failed

Kafka user lacks DESCRIBE_CONFIGS ACL required for auto topic creation with default settings.

Pre-create topics and disable AutoCreateTopic, or configure PartitionCount and ReplicationFactor explicitly in DataTopicConfig.

Authorization failed

The authenticated Kafka user does not have all required ACLs.

Grant all required ACLs per the Required ACLs table.

Connection Retry Policy '<key>' must be a valid number

Value for retryDelayMultiplier or maxAttempts is not numeric.

Provide a valid numeric value, digits only. Example: maxAttempts=5, retryDelayMultiplier=2.

Connection Retry Policy '<key>' must be a non-negative/positive value

Time parameters need ≥ 0; numeric parameters (retryDelayMultiplier, maxAttempts) need > 0.

Use non-negative values for time parameters and positive values for numeric parameters. Check for stray negative signs or zeros.

Invalid DataTopicConfig properties: <key>

DataTopicConfig contains a property name that isn't a recognized Kafka topic configuration.

Use only supported properties: PartitionCount, ReplicationFactor, MaxMessageSize, RetentionSize, RetentionTime, CleanUpPolicy.

Message Key must be provided if cleanup.policy is set to compact

DataTopicConfig sets cleanup.policy to compact but MessageKey is not configured.

Set MessageKey to PrimaryKey or Custom, or change cleanup.policy to delete if compaction isn't needed.

Data topic name '<topicName>' contains wildcard character (%) which is only allowed with topic mapping

The Topics property has a % character without mapping syntax.

Use topic mapping format, e.g. 'source,TopicName%', or remove the % if wildcarding isn't needed.

Data topic name '<topicName>' is not valid

The resolved topic name contains characters Kafka doesn't allow.

Use only alphanumeric characters, dot (.), underscore (_), and hyphen (-); use explicit mapping for source names with unsupported characters.

Data topic name '<topicName>' exceeds the length limit of 249 characters

The resolved topic name is longer than Kafka's 249-character limit.

Shorten the topic name via explicit mapping, or remove long wildcard prefixes/suffixes.

Topic replication factor must be 3

Confluent Cloud enforces a fixed replication factor of 3.

Remove the replication.factor override from TopicConfig, or set it explicitly to 3.

Custom Message Key must be in 'key=value;key2=value2' format

CustomMessageKey isn't in valid key=value pair format.

Use key=value pairs separated by semicolons, e.g. id=customerId;region=state.

Message Header must be in 'key=value;key2=value2' format

MessageHeader isn't in valid key=value pair format.

Use key=value pairs separated by semicolons, e.g. source=application;table=@metadata(TableName).

Invalid SchemaEvolution value

SchemaEvolution is set to a value other than Auto or Manual.

Use only Auto or Manual; check for typos.

Problem getting token <name> from event data fields

A field referenced in TopicKey, PartitionKey, MessageKey, or MessageHeader doesn't exist in the event's type definition.

Verify the field exists (case-sensitive) using DESCRIBE TYPE.