zitadel/zitadel · error

cache connector %q not enabled

Error message

cache connector %q not enabled

What it means

StartCache returns this error when the requested cache purpose/configuration requires a connector (memory, etc.) that was not initialized/enabled in the connectors registry. If the connector struct field for the configured connector type is nil, no cache implementation can be built, so startup fails with a quoted connector name in the message.

Source

Thrown at backend/v3/storage/cache/connector/connector.go:48

		return Connectors{}, nil
	}
	return Connectors{
		Config: *conf,
		Memory: gomap.NewConnector(conf.Connectors.Memory),
	}, nil
}

func StartCache[I ~int, K ~string, V cache.Entry[I, K]](background context.Context, indices []I, purpose cache.Purpose, conf *cache.Config, connectors Connectors) (cache.Cache[I, K, V], error) {
	if conf == nil || conf.Connector == cache.ConnectorUnspecified {
		return noop.NewCache[I, K, V](), nil
	}
	if conf.Connector == cache.ConnectorMemory && connectors.Memory != nil {
		c := gomap.NewCache[I, K, V](background, indices, *conf)
		connectors.Memory.Config.StartAutoPrune(background, c, purpose)
		return c, nil
	}

	return nil, fmt.Errorf("cache connector %q not enabled", conf.Connector)
}

View on GitHub (pinned to 13948f2bcd)

Solutions

1. Configure and enable the connector named in the error (e.g. the memory or redis cache connector section in config)
2. Ensure the connector startup ran before StartCache (startCaches wiring) so the registry entry is non-nil
3. If caching is not desired, disable the cache purpose in the configuration instead of leaving a dangling connector reference

Example fix

// before
Cache:
  Connectors:
    # no redis configured, purpose references redis
// after
Cache:
  Connectors:
    Redis:
      Enabled: true
      Addresses: [localhost:6379]

if conf.Connector == cache.ConnectorMemory && connectors.Memory == nil {
	return fmt.Errorf("memory cache connector is not enabled; configure Cache.Connectors.Memory")
}

c, err := cache.StartCache[I, K, V](background, indices, conf, connectors)
if err != nil {
	return fmt.Errorf("starting cache: %w", err)
}

When it happens

Trigger: Config enables a cache purpose with Connector set to a type whose entry in the connectors struct is nil — e.g. config says memory/redis but startAPIs/startCaches only wired up a different connector, or the connector's own startup was skipped/disabled.

Common situations: Enabling caching features (e.g. in newer ZITADEL versions) without configuring the corresponding cache connector section; partially enabled config files after upgrades; typos making the connector type mismatch the initialized one.

Related errors

• TLS is enabled: please specify a key (path) and a cert (path
• unable to start caches: %w
• MaxOpenConns of the database must be higher than 3 or 0 for
• MaxIdleConns of the database must be higher than 3 or 0 for
• unable to append rootCA

AI-assisted analysis of zitadel/zitadel@13948f2bcd (2026-09-06). Data as JSON: /api/errors/4b3bbd562977fc0c. Report an issue: GitHub.