thanos-io/thanos · error

failed to validate hashring configuration file

Error message

failed to validate hashring configuration file

What it means

Wraps a failure of receive.NewConfigWatcher, which validates and starts watching the hashring configuration file given by --receive.hashrings-file. It fires when the file cannot be stat'ed, read, or does not conform to the hashring JSON schema; the multi-node receive setup aborts because it cannot track hashring membership changes.

Solutions

1. Fix hashring JSON structure (hashrings array, endpoints)
2. Validate with the hashring config schema
3. Check for trailing commas or wrong types

When it happens

Trigger: Thrown at cmd/thanos/receive.go:611 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at cmd/thanos/receive.go:611

	// Note: the hashring configuration watcher
	// is the sender and thus closes the chan.
	// In the single-node case, which has no configuration
	// watcher, we close the chan ourselves.
	updates := make(chan []receive.HashringConfig, 1)
	algorithm := receive.HashringAlgorithm(conf.hashringsAlgorithm)

	// The Hashrings config file path is given initializing config watcher.
	if conf.hashringsFilePath != "" {
		cw, err := receive.NewConfigWatcher(log.With(logger, "component", "config-watcher"), reg, conf.hashringsFilePath, *conf.refreshInterval)
		if err != nil {
			return errors.Wrap(err, "failed to initialize config watcher")
		}

		// Check the hashring configuration on before running the watcher.
		if err := cw.ValidateConfig(); err != nil {
			cw.Stop()
			close(updates)
			return errors.Wrap(err, "failed to validate hashring configuration file")
		}

		ctx, cancel := context.WithCancel(context.Background())
		g.Add(func() error {
			return receive.ConfigFromWatcher(ctx, updates, cw)
		}, func(error) {
			cancel()
		})
	} else {
		var (
			cf  []receive.HashringConfig
			err error
		)
		// The Hashrings config file content given initialize configuration from content.
		if len(conf.hashringsFileContent) > 0 {
			cf, err = receive.ParseConfig([]byte(conf.hashringsFileContent))
			if err != nil {
				close(updates)

View on GitHub (pinned to 35b8b99117)