jaegertracing/jaeger · error

cannot load config file: %w

Error message

cannot load config file: %w

What it means

Service.Start is the bootstrap for Jaeger services; its first step loads the config file via TryLoadConfigFile, and any error there is re-wrapped as "cannot load config file". This is the outer wrapper users see when --config-file is bad; the inner cause names the actual file and Viper error.

Source

Thrown at cmd/internal/flags/service.go:65

	return &Service{
		Admin:          NewAdminServer(ports.PortToHostPort(adminPort)),
		signalsChannel: signalsChannel,
	}
}

// AddFlags registers CLI flags.
func (s *Service) AddFlags(flagSet *flag.FlagSet) {
	AddConfigFileFlag(flagSet)
	AddLoggingFlags(flagSet)
	metricsbuilder.AddFlags(flagSet)
	s.Admin.AddFlags(flagSet)
	featuregate.GlobalRegistry().RegisterFlags(flagSet)
}

// Start bootstraps the service and starts the admin server.
func (s *Service) Start(v *viper.Viper) error {
	if err := TryLoadConfigFile(v); err != nil {
		return fmt.Errorf("cannot load config file: %w", err)
	}

	sFlags := new(SharedFlags).InitFromViper(v)
	newProdConfig := zap.NewProductionConfig()
	newProdConfig.Sampling = nil
	logger, err := sFlags.NewLogger(newProdConfig)
	if err != nil {
		return fmt.Errorf("cannot create logger: %w", err)
	}
	s.Logger = logger
	grpclog.SetLoggerV2(zapgrpc.NewLogger(
		logger.WithOptions(
			zap.AddCallerSkip(5), // ensure the actual caller:lineNo is shown
		),
	))

	metricsBuilder := new(metricsbuilder.Builder).InitFromViper(v)
	metricsFactory, err := metricsBuilder.CreateMetricsFactory("")

View on GitHub (pinned to 806f444784)

Solutions

1. Look at the chained cause for the exact file and Viper error.
2. Fix the path/permissions or correct the YAML/JSON syntax.
3. Validate the config file parses before deploying (yamllint/jq).
4. If no config file is intended, remove the --config-file flag entirely.

Example fix

// before
args: ["--config-file=/etc/jaeger/config.yaml"]  # ConfigMap not mounted
// after: add the volume mount
volumeMounts: [{ name: jaeger-config, mountPath: /etc/jaeger }]

if cf := v.GetString("config-file"); cf != "" {
    if fi, err := os.Stat(cf); err != nil || fi.IsDir() {
        return fmt.Errorf("bad --config-file %s", cf)
    }
}

if err := svc.Start(v); err != nil {
    if strings.Contains(err.Error(), "cannot load config file") {
        // check --config-file path and syntax per the wrapped cause
    }
    return err
}

When it happens

Trigger: Starting any Jaeger service (all-in-one, collector, query) with --config-file set to a missing, unreadable, or syntactically invalid file, so TryLoadConfigFile returns an error and Start aborts.

Common situations: Wrong path in a K8s args list; ConfigMap key renamed; YAML syntax error; file mounted with restrictive permissions; docker-compose volume not mounted.

Related errors

• unknown metrics backend specified
• failed to initialize config: %w
• cannot load config file %s: %w
• cannot create metrics factory: %w
• cannot initialize admin server: %w

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