What causes "configuration file is empty" in thanos-io/thanos?

Populate the file with at least one hashring entry containing a non-empty endpoints list

configuration file is empty

Error message

configuration file is empty

What it means

errEmptyConfigurationFile is a sentinel returned by loadConfig when the hashring file parses successfully but yields an empty configuration (len(config) == 0) — e.g. the file is empty, contains only whitespace, or a zero-length hashring list. Receive requires at least one hashring entry to route series, so an empty config is rejected.

Solutions

Populate the file with at least one hashring entry containing a non-empty endpoints list
Make config updates atomic (temp file + rename) so watchers never see an empty intermediate state
Verify the ConfigMap/secret volume actually mounted content (check for emptyDir fallback)
Compare the deployed file against the intended hashring topology

Example fix

// before
[]
// after
[{"endpoints": [{"address": "recv-0:10901"}, {"address": "recv-1:10901"}]}]

Defensive patterns

Strategy: validation

Validate before calling

var v []map[string]interface{}
if err := json.Unmarshal(content, &v); err != nil {
	return err
}
if len(v) == 0 {
	return errors.New("hashring config is empty; at least one entry required")
}

Try / catch

if errors.Is(err, errEmptyConfigurationFile) {
	// block rollout; regenerate config with real endpoints
}

Prevention

Never deploy a hashring config that renders to an empty list; assert in your templating pipeline
Use atomic replace so the watcher never observes an empty intermediate file
Alert when a rendered config has zero endpoints

When it happens

Trigger: loadConfig reads a file whose parsed result is an empty slice or nil: empty file, `[]` as the whole config, or a config-management tool clearing the file during an update.

Common situations: Kubernetes ConfigMap momentarily emptied during an update; a template renderer producing an empty output; operator accidentally deploying `[]` instead of the hashring list.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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

Appendix: source

Thrown at pkg/receive/config.go:32

	"path/filepath"
	"strings"
	"time"

	"github.com/fsnotify/fsnotify"
	"github.com/go-kit/log"
	"github.com/go-kit/log/level"
	"github.com/pkg/errors"
	"github.com/prometheus/client_golang/prometheus"
	"github.com/prometheus/client_golang/prometheus/promauto"
	"github.com/prometheus/common/model"
	"github.com/prometheus/prometheus/model/labels"
)

var (
	// An errParseConfigurationFile is returned by the ConfigWatcher when parsing failed.
	errParseConfigurationFile = errors.New("configuration file is not parsable")
	// An errEmptyConfigurationFile is returned by the ConfigWatcher when attempting to load an empty configuration file.
	errEmptyConfigurationFile = errors.New("configuration file is empty")
)

type ReceiverMode string

const (
	RouterOnly     ReceiverMode = "RouterOnly"
	IngestorOnly   ReceiverMode = "IngestorOnly"
	RouterIngestor ReceiverMode = "RouterIngestor"

	DefaultCapNProtoPort string = "19391"
)

type endpoints []Endpoint

func (e endpoints) Len() int {
	return len(e)
}

View on GitHub (pinned to 35b8b99117)