What causes "storage '%s' not declared in '%s' extension configuration" in jaegertracing/jaeger?

Declare the referenced storage name under the jaegerstorage extension's backends (TraceBackends) in the config

storage '%s' not declared in '%s' extension configuration

Error message

storage '%s' not declared in '%s' extension configuration

What it means

TraceStorageFactory lazily creates trace factories on demand. It first checks s.config.TraceBackends for the requested name; if the name was never declared in the jaegerstorage extension configuration, it returns this error naming both the storage and the component type. This catches references from other components (query, ingester, exporter) to storages that were never defined.

Source

Thrown at cmd/jaeger/internal/extension/jaegerstorage/extension.go:191

			}
		}
	}
	return errors.Join(errs...)
}

func (s *storageExt) TraceStorageFactory(name string) (tracestore.Factory, error) {
	s.factoryMu.Lock()
	defer s.factoryMu.Unlock()

	// Return cached factory if already created
	if f, ok := s.factories[name]; ok {
		return f, nil
	}

	// Check if configuration exists
	cfg, ok := s.config.TraceBackends[name]
	if !ok {
		return nil, fmt.Errorf(
			"storage '%s' not declared in '%s' extension configuration",
			name, componentType,
		)
	}

	// Create factory on demand
	factory, err := storageconfig.CreateTraceStorageFactory(
		context.Background(),
		name,
		cfg,
		s.telset,
		func(authCfg config.Authentication, backendType, backendName string) (extensionauth.HTTPClient, error) {
			return s.resolveAuthenticator(s.telset.Host, authCfg, backendType, backendName)
		},
	)
	if err != nil {
		return nil, fmt.Errorf("failed to initialize storage '%s': %w", name, err)
	}

View on GitHub (pinned to 806f444784)

Solutions

Declare the referenced storage name under the jaegerstorage extension's backends (TraceBackends) in the config
Fix the consumer's storage name to match an existing declared backend exactly
Keep names consistent between jaegerstorage backends and all referencing components; validate config before deploy

Example fix

// before: query references undeclared name
service:
  extensions: [jaegerstorage]
extensions:
  jaegerstorage:
    backends:
      primary: { memory: {} }
# query.storage.traces_main: "main"  -> not declared
// after
# query.storage.traces_main: "primary"  (matches declared backend)

Defensive patterns

Strategy: validation

Validate before calling

// pre-check name against declared backends
func hasTraceBackend(name string, cfg *jaegerstorage.Config) bool {
    _, ok := cfg.TraceBackends[name]
    return ok
}

Try / catch

f, err := jaegerstorage.GetTraceStoreFactory(name, host)
if err != nil {
    if strings.Contains(err.Error(), "not declared in") {
        return fmt.Errorf("storage name '%s' must match a backend under jaegerstorage extensions config", name)
    }
    return err
}

Prevention

Use a shared constant/config variable for storage names across components
Diff consumer storage names against jaegerstorage backends in config linting
Rename backends and consumers together (search all `storage:` references)

When it happens

Trigger: Calling jaegerstorage.GetTraceStoreFactory(name, host) (or equivalent via getStorageFactory) with a name absent from the extension's TraceBackends map and not present in the cached factories map.

Common situations: Typo in the storage name in query.storage.* or exporter config, renaming a backend entry in jaegerstorage config without updating consumers, or referencing trace storage from a component whose name only exists under metric_backends.

Related errors

AI-assisted analysis of jaegertracing/jaeger@806f444784 (2026-09-01). Data as JSON: /api/errors/87df7463bc5475d7. Report an issue: GitHub.