jaegertracing/jaeger · error

failed to initialize storage '%s': %w

Error message

failed to initialize storage '%s': %w

What it means

CreateTraceStorageFactory builds a storage.Factory for a named trace backend using the configured type (memory, badger, cassandra, elasticsearch/opensearch, grpc, clickhouse). When the type-specific constructor returns an error — connection refused, bad credentials, invalid options, or an 'empty configuration' fallback for an unknown type — it is wrapped as `failed to initialize storage '%s': %w` naming the backend.

Source

Thrown at cmd/internal/storageconfig/factory.go:87

		}
		factory, err = es.NewFactory(ctx, *backend.Elasticsearch, telset, httpAuth)
	case backend.Opensearch != nil:
		var httpAuth extensionauth.HTTPClient
		if authResolver != nil {
			httpAuth, err = authResolver(backend.Opensearch.Authentication, "opensearch", name)
			if err != nil {
				return nil, err
			}
		}
		factory, err = es.NewFactory(ctx, *backend.Opensearch, telset, httpAuth)
	case backend.ClickHouse != nil:
		factory, err = clickhouse.NewFactory(ctx, *backend.ClickHouse, telset)
	default:
		err = errors.New("empty configuration")
	}

	if err != nil {
		return nil, fmt.Errorf("failed to initialize storage '%s': %w", name, err)
	}

	return factory, nil
}

View on GitHub (pinned to 806f444784)

Solutions

1. Read the wrapped cause after 'failed to initialize storage NAME' — it names the real failure (connection refused, auth failed, empty configuration, etc.)
2. If the cause is 'empty configuration', the named backend has no recognized type field set — add exactly one storage type to that entry
3. Verify connectivity from the Jaeger host to the storage backend (host, port, TLS) and fix credentials in the backend config
4. For Cassandra/Elasticsearch, ensure the schema/keyspace/index was initialized (e.g. jaeger-cassandra-schema / index templates) before starting
5. Order deployment so the storage service is ready before Jaeger starts, or add retry/readiness gating

Example fix

// before (config.yaml)
jaeger:
  storage:
    trace_backends:
      main:
        elasticsearch:
          servers: http://es:9200
          index_prefix: ""   # ok
          # but ES actually requires auth here
// after
jaeger:
  storage:
    trace_backends:
      main:
        elasticsearch:
          servers: http://es:9200
          authentication:
            basic:
              username: elastic
              password: "${ES_PASSWORD}"

// Pre-check connectivity for networked backends before calling CreateTraceStorageFactory
for _, be := range []struct{ name string; addr string }{
    {"cassandra", cfg.Cassandra.Servers[0]},
    {"elasticsearch", cfg.Elasticsearch.Servers[0]},
    {"clickhouse", cfg.ClickHouse.Address},
} {
    conn, err := net.DialTimeout("tcp", be.addr, 3*time.Second)
    if err != nil {
        return fmt.Errorf("storage %s unreachable at %s: %w", be.name, be.addr, err)
    }
    conn.Close()
}

factory, err := f.CreateTraceStorageFactory(ctx, name, backend, telset)
if err != nil {
    if strings.Contains(err.Error(), "empty configuration") {
        // backend type field missing on this named entry; fix config
    } else {
        // connection/auth/schema failure — inspect cause via errors.Unwrap
    }
    return err
}

When it happens

Trigger: Calling CreateTraceStorageFactory(ctx, name, backend, telset) where the constructor for the configured backend type fails: Cassandra/Elasticsearch/ClickHouse unreachable or with bad auth, gRPC remote-storage address unresolvable, or backend struct with no type set (hits the default 'empty configuration' branch).

Common situations: Database not up yet or wrong hostname/port in the backend config; wrong username/password or TLS settings for Elasticsearch/Cassandra; keyspace/index templates missing; named backend entry whose type field is missing so the default branch triggers; storage plugin dependency versions mismatched.

Related errors

• unknown metrics backend specified
• cannot load config file: %w
• cannot create metrics factory: %w
• cannot initialize admin server: %w
• multiple backend types found for trace storage: %v

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