thanos-io/thanos · error

failed to read configuration file

Error message

failed to read configuration file

What it means

loadConfig wraps any failure from readFile(logger, path) — reading the raw hashring configuration file — with 'failed to read configuration file'. This fires before parsing, so it indicates an I/O-level problem (missing file, permission denied, read error) rather than a content problem.

Solutions

1. Verify the file exists at the exact configured path and is readable by the process (ls -l, cat as the run user)
2. Fix the --hashrings-file flag or mount configuration so the file is present
3. Restore the file if it was deleted mid-run; the periodic refresh will pick it up on the next interval
4. Check volume mount permissions/ownership for non-root containers

Example fix

// before
hashringsFile: "/etc/thanos/wrong-name.json"
// after
hashringsFile: "/etc/thanos/hashrings.json"  # mounted, mode 0444

info, err := os.Stat(path)
if err != nil { return fmt.Errorf("config file not accessible: %w", err) }
if !info.Mode().IsRegular() { return errors.New("config path is not a regular file") }
f, err := os.Open(path)
if err != nil { return fmt.Errorf("permission denied reading config: %w", err) }
f.Close()

_, _, err := receive.ValidateConfig(logger, path)
if err != nil && strings.Contains(err.Error(), "failed to read configuration file") {
	// check path/mount/permissions before restarting
}

When it happens

Trigger: loadConfig -> readFile fails: the --hashrings-file path does not exist, permissions deny reading, the path is a directory, or an I/O error occurs while reading.

Common situations: ConfigMap/secret not mounted at the expected path; wrong flag value; file deleted while the config watcher's periodic refresh runs; non-root process lacking read permission on a root-owned mount.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• unable to load config content
• unable to load config file
• configuration file is not parsable
• configuration file is empty
• endpoint address must be set

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

Appendix: source

Thrown at pkg/receive/config.go:397

			updates <- cfg
		case <-ctx.Done():
			return ctx.Err()
		}
	}
}

// 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))

View on GitHub (pinned to 35b8b99117)