What causes "nil kafka config" in openimsdk/open-im-server?

Add a complete kafka config block (addresses/topics) to the config file

nil kafka config

Error message

nil kafka config

What it means

NewBuilder selects a message-queue implementation from queue.Engine. When the engine is Kafka, a non-nil kafka config is required; if kafka is nil the builder returns 'nil kafka config' because it cannot construct the Kafka builder.

Source

Thrown at pkg/mqbuild/builder.go:43

	TopicToOfflinePush = "toOfflinePush"
)

const (
	GroupRedis       = "redis"
	GroupMongo       = "mongo"
	GroupPush        = "push"
	GroupOfflinePush = "offlinePush"
)

func NewBuilder(queue config.EngineSelector, kafka *config.Kafka, redis redis.UniversalClient) (Builder, error) {
	engine, err := config.ValidateQueueEngine(queue.Engine, config.Standalone())
	if err != nil {
		return nil, err
	}
	switch engine {
	case config.QueueEngineKafka:
		if kafka == nil {
			return nil, fmt.Errorf("nil kafka config")
		}
		return newKafkaBuilder(kafka), nil
	case config.QueueEngineRedis:
		return newRedisBuilder(redis), nil
	case config.QueueEngineMemory:
		return standaloneBuilder{}, nil
	default:
		return nil, fmt.Errorf("unsupported queue engine %s", queue.Engine)
	}
}

func newKafkaBuilder(kafka *config.Kafka) Builder {
	topics := MergeTopics(KafkaTopics(kafka))
	return &kafkaBuilder{
		addr:         kafka.Address,
		config:       kafka.Build(),
		logicalTopic: LogicalTopicNames(topics),
		topicGroupID: TopicGroupID(topics),

View on GitHub (pinned to 175a7bb067)

Solutions

Add a complete kafka config block (addresses/topics) to the config file
Or change queue.Engine to redis/memory if Kafka is not intended
Validate the config at load time before calling Start

Example fix

// before
queue:
  engine: kafka
// after
queue:
  engine: kafka
  kafka:
    username: ""
    password: ""
    addr: [ "127.0.0.1:9092" ]
    topics: ...

Defensive patterns

Strategy: validation

Validate before calling

if cfg.Queue.Engine == config.QueueEngineKafka && cfg.Queue.Kafka == nil {
    return errors.New("queue engine is kafka but kafka config section is missing")
}

Try / catch

b, err := mqbuild.NewBuilder(redis, kafka, queue, opts)
if err != nil && strings.Contains(err.Error(), "nil kafka config") {
    // reload config or fall back to redis engine
}

Prevention

Validate the full queue config struct at startup
Keep engine selection and its config section in sync
Use config schema validation (e.g. required-if rules) in CI

When it happens

Trigger: Start() calls mqbuild.NewBuilder with queue config where Engine == config.QueueEngineKafka but the Kafka section of the config is absent/null.

Common situations: Config file switched engine to kafka without filling the kafka block; env-based config injection missed the kafka section; partial config merge dropped the kafka key.

Related errors

AI-assisted analysis of openimsdk/open-im-server@175a7bb067 (2026-09-04). Data as JSON: /api/errors/5c2845b4b21abe9b. Report an issue: GitHub.