thanos-io/thanos · error

failed to parse configuration file

Error message

failed to parse configuration file: %v

What it means

loadConfig wraps any error from ParseConfig with the message 'failed to parse configuration file', preserving the underlying parse error. The receiver's configuration file must be valid THanos-style hashring configuration; if its content cannot be parsed into a []HashringConfig, this error is returned. The wrapped sentinel errParseConfigurationFile allows programmatic detection.

Solutions

1. Validate the config before deployment with the Thanos `thanos tools bucket verify`-style sidecar tooling or by calling ValidateConfig on startup
2. Fix the YAML/JSON syntax and schema in the configuration file (check field names: tops, hashes, endpoints)
3. Check the wrapped error (%v at the end of the message) for the exact line/field that failed to unmarshal
4. Confirm the file at the --receive.config-file path contains hashring config, not another format

Example fix

// before (broken hashring YAML)
hashring:tenant-a:
  - endpoints: ['thanos-receive-0:10901']
// after
tenants:
  - endpoints: ['thanos-receive-0:10901']

if err := rcv.ValidateConfig(cfgBytes); err != nil { return fmt.Errorf("invalid receive config: %w", err) }

if _, _, err := receive.ValidateConfig(cfg); err != nil {
    if errors.Is(err, receive.ErrParseConfigurationFile) { /* handle schema error */ }
    return err
}

When it happens

Trigger: loadConfig (called by ValidateConfig and refresh) reads the config file successfully but ParseConfig fails — i.e. the file content is malformed YAML/JSON or does not unmarshal into the expected hashring schema.

Common situations: Hand-edited hashring configuration with wrong indentation, missing 'endpoints' field, wrong types (string where a list is expected), a file that is valid YAML but not valid hashring config, or an empty/garbage file passed via --receive.config-file.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• configuration file is not parsable
• parsing config YAML file
• level is bigger then default set of
• unknown sync strategy
• create syncer

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

Appendix: source

Thrown at pkg/receive/config.go:402

}

// ParseConfig parses the raw configuration content and returns a HashringConfig.
func ParseConfig(content []byte) ([]HashringConfig, error) {
	var config []HashringConfig
	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 {

View on GitHub (pinned to 35b8b99117)