What causes "could not create jaeger-query: %w" in jaegertracing/jaeger?

Inspect the wrapped error for which server option failed validation

could not create jaeger-query: %w

Error message

could not create jaeger-query: %w

What it means

After assembling readers and options, Start constructs the actual query HTTP/gRPC server via queryapp.NewServer. If server construction fails (invalid query options, bad listen addresses/ports in config, etc.), the error is wrapped as 'could not create jaeger-query'.

Source

Thrown at cmd/jaeger/internal/extension/jaegerquery/server.go:144

			ArchiveStorage:           archiveStorage,
			MetricsStorage:           metricsStorage,
			SearchWithoutServiceName: searchWithoutServiceName,
			AIAssistant:              s.aiHealth != nil && s.aiHealth.Current(),
		}
	}

	s.server, err = queryapp.NewServer(
		ctx,
		// TODO propagate healthcheck updates up to the collector's runtime
		qs,
		mqs,
		&s.config.QueryOptions,
		backendCaps,
		tm,
		telset,
	)
	if err != nil {
		return fmt.Errorf("could not create jaeger-query: %w", err)
	}

	if err := s.server.Start(ctx); err != nil {
		return fmt.Errorf("could not start jaeger-query: %w", err)
	}

	// Start the health checker only after the query server is up — a failed
	// server start (e.g. port bind error) returns an error from Start, and
	// the OTel collector does not call Shutdown in that case. Starting the
	// checker first would leak its goroutine forever. The checker is given a
	// fresh background context because the Start context is cancelled when
	// Start returns; Shutdown stops the checker explicitly.
	if s.aiHealth != nil {
		s.aiHealth.Start(context.Background()) //nolint:contextcheck // intentional: checker outlives Start ctx; Shutdown stops it.
	}

	return nil
}

View on GitHub (pinned to 806f444784)

Solutions

Inspect the wrapped error for which server option failed validation
Fix the http/grpc endpoint and base_path values in the jaeger_query extension config
Validate TLS/tenancy settings (cert file paths exist, formats valid)
Try a minimal known-good query options config to isolate the failing field

Example fix

// before
jaeger_query:
  grpc:
    endpoint: ":0grpc"
// after
jaeger_query:
  grpc:
    endpoint: ":16685"

Defensive patterns

Strategy: validation

Validate before calling

// Validate query options before Start
for _, ep := range []string{cfg.QueryOptions.HTTP.Endpoint, cfg.QueryOptions.GRPC.Endpoint} {
	if _, _, err := net.SplitHostPort(ep); err != nil {
		return fmt.Errorf("invalid endpoint %q: %w", ep, err)
	}
}

Try / catch

if err := ext.Start(ctx, host); err != nil {
	if strings.Contains(err.Error(), "could not create jaeger-query") {
		log.Fatalf("query server construction failed: %v — check query options", err)
	}
	return err
}

Prevention

Validate endpoint strings, base_path, and TLS file paths before deploy
Start from a known-good sample config and diff changes
Run config linting in CI for the collector config
Avoid exotic characters in endpoint/base_path values

When it happens

Trigger: queryapp.NewServer returns an error — typically invalid QueryOptions configuration such as malformed HTTP/gRPC endpoints, invalid base path, or failure building server components from config.

Common situations: Invalid http/grpc endpoint strings or reserved ports in query options; base_path conflicts; misconfigured tenancy or TLS options rejected at construction time.

Related errors

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