thanos-io/thanos · error

unable to load config initially

Error message

unable to load config initially

What it means

Wrapper in setupEndpointSet for failures from newEndpointConfigProvider during the initial endpoint config load. Any of the inner failures — file read, YAML unmarshal, validation, or reloader creation — surfaces here, preventing the Query/Rule endpoint set from starting. The specific cause is always chained below this message.

Solutions

1. Read the full chained error to identify whether it was load, unmarshal, validate, or reloader; fix that specific issue.
2. Verify the config file exists, is valid YAML matching EndpointConfig, and passes strict-mode rules before startup.
3. As a quick unblock, switch to static --endpoint flags to confirm endpoint setup otherwise works, then fix the file.
4. In k8s, ensure the ConfigMap is mounted and readable before the container entrypoint runs.

Example fix

// before
// thanos query --endpoint-config=/etc/thanos/endpoints.yaml   # file missing -> fails
// after: validate in CI/startup
// thanos tools bucket ... # no; instead pre-validate:// yq eval '.' /etc/thanos/endpoints.yaml > /dev/null && exec thanos query --endpoint-config=/etc/thanos/endpoints.yaml

func preflight(cfgPath string) error { if cfgPath == "" { return nil }; b, err := os.ReadFile(cfgPath); if err != nil { return err }; var c EndpointConfig; if err := yaml.Unmarshal(b, &c); err != nil { return err }; return validateEndpointConfig(&c) }

ep, err := setupEndpointSet(ctx, g, logger, reg, ..., configFile)
if err != nil {
    if strings.Contains(err.Error(), "unable to load config initially") {
        log.Fatalf("endpoint setup failed at startup: %v", err)
    }
    return err
}

When it happens

Trigger: setupEndpointSet is invoked by runQuery/runRule (or callers) and calls newEndpointConfigProvider(legacy flags + configFile); any parse/validate/reloader error propagates wrapped as 'unable to load config initially'.

Common situations: First boot of thanos query with a bad --endpoint-config file (missing, malformed, or invalid entries); typo in legacy --endpoint flags combined with file config producing validation failures; permissions on the mounted config.

Understand the failure class

Background: "Config file not found": what it means and how to fix it in docker-sync, Maven, Vagrant, Turborepo and other tools — this error's family across 60 libraries.

Related errors

• unable to load config content
• unable to load config file
• unable to create config reloader
• tracing failed
• query configuration

AI-assisted analysis of thanos-io/thanos@35b8b99117 (2026-09-07). Data as JSON: /api/errors/2f45c549c82e3ba4. Report an issue: GitHub.

Appendix: source

Thrown at cmd/thanos/endpointset.go:319

	queryTimeout time.Duration,
	dialOpts []grpc.DialOption,
	globalTLSConfig *tlsConfig,
	globalTLSOpt grpc.DialOption,
	globalCompression string,
	injectTestAddresses []string,
	queryConnMetricLabels ...string,
) (*query.EndpointSet, error) {
	configProvider, err := newEndpointConfigProvider(
		logger,
		configFile,
		configReloadInterval,
		legacyEndpoints,
		legacyEndpointGroups,
		legacyStrictEndpoints,
		legacyStrictEndpointGroups,
	)
	if err != nil {
		return nil, errors.Wrapf(err, "unable to load config initially")
	}
	// Register resolver for the "thanos:///" scheme for endpoint-groups
	dns.RegisterGRPCResolver(
		logger,
		dns.NewProvider(
			logger,
			extprom.WrapRegistererWithPrefix(fmt.Sprintf("thanos_%s_endpoint_groups_", comp), reg),
			dns.ResolverType(dnsSDResolver),
		),
		dnsSDInterval,
		injectTestAddresses,
	)
	dnsEndpointProvider := dns.NewProvider(
		logger,
		extprom.WrapRegistererWithPrefix(fmt.Sprintf("thanos_%s_endpoints_", comp), reg),
		dns.ResolverType(dnsSDResolver),
	)
	duplicatedEndpoints := promauto.With(reg).NewCounter(prometheus.CounterOpts{

View on GitHub (pinned to 35b8b99117)