thanos-io/thanos · error

failed to load configuration file, path

Error message

failed to load configuration file, path: %s

What it means

loadConfig wraps the sentinel errEmptyConfigurationFile when the parsed configuration yields an empty hashring list (len(config) == 0). This means the file was readable and parseable but contained no hashring entries, so the receiver would have nowhere to route/replicate writes.

Solutions

1. Populate the hashring configuration with at least one entry containing valid endpoints
2. If the receiver is meant to run with hashring disabled, use the appropriate no-hashing flag instead of an empty hashring file
3. Check the rendered file on disk (`cat`) to confirm your config management actually wrote the entries
4. Verify the parse step is not silently discarding entries due to wrong top-level key

Example fix

// before: empty config file
# (no entries)
// after
- endpoints:
    - thanos-receive-0.thanos-receive:10901
    - thanos-receive-1.thanos-receive:10901

cfg, _, err := receive.ValidateConfig(cfgBytes)
if err != nil { return err }
if len(cfg) == 0 { return errors.New("hashring config must contain at least one entry") }

if err != nil && errors.Is(err, receive.ErrEmptyConfigurationFile) {
    log.Error("hashring config is empty; refusing to start")
}

When it happens

Trigger: loadConfig successfully reads and parses the file, but ParseConfig returns a zero-length []HashringConfig — e.g. the file contains an empty list, only comments, or a YAML document that unmarshals to no hashrings.

Common situations: An operator points --receive.config-file at a placeholder/empty file, the config management tool rendered the file to an empty list, or the file was truncated after a failed templating deploy.

Understand the failure class

Background: EmptyResultError / "no results found": when an API or scraper succeeds but returns zero rows — this error's family across 9 libraries.

Related errors

• configuration file is empty
• configuration file is not parsable
• endpoint address must be set
• failed to read configuration file
• error matching tenant pattern

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

Appendix: source

Thrown at pkg/receive/config.go:407

	err := json.Unmarshal(content, &config)
	return config, err
}

// loadConfig loads raw configuration content and returns a configuration.
func loadConfig(logger log.Logger, path string) ([]HashringConfig, float64, error) {
	cfgContent, err := readFile(logger, path)
	if err != nil {
		return nil, 0, errors.Wrap(err, "failed to read configuration file")
	}

	config, err := ParseConfig(cfgContent)
	if err != nil {
		return nil, 0, errors.Wrapf(errParseConfigurationFile, "failed to parse configuration file: %v", err)
	}

	// If hashring is empty, return an error.
	if len(config) == 0 {
		return nil, 0, errors.Wrapf(errEmptyConfigurationFile, "failed to load configuration file, path: %s", path)
	}

	return config, hashAsMetricValue(cfgContent), nil
}

// readFile reads the configuration file and returns content of configuration file.
func readFile(logger log.Logger, path string) ([]byte, error) {
	fd, err := os.Open(filepath.Clean(path))
	if err != nil {
		return nil, err
	}
	defer func() {
		if err := fd.Close(); err != nil {
			level.Error(logger).Log("msg", "failed to close file", "err", err, "path", path)
		}
	}()

	return io.ReadAll(fd)

View on GitHub (pinned to 35b8b99117)