What causes "couldn't load repositories file (%s): %w" in helm/helm?

Check the expected path: `helm env | grep HELM_CONFIG_HOME`, then inspect /helm/repositories.yaml

couldn't load repositories file (%s): %w

Error message

couldn't load repositories file (%s): %w

What it means

repo.LoadFile failed to read the repositories.yaml file - os.ReadFile returned an error such as file-not-exists or permission-denied. Note the function still returns a non-nil, empty *File alongside the error, so callers must decide whether a missing file is fatal or just means no repositories are configured.

Source

Thrown at pkg/repo/v1/repo.go:51

}

// NewFile generates an empty repositories file.
//
// Generated and APIVersion are automatically set.
func NewFile() *File {
	return &File{
		APIVersion:   APIVersionV1,
		Generated:    time.Now(),
		Repositories: []*Entry{},
	}
}

// LoadFile takes a file at the given path and returns a File object
func LoadFile(path string) (*File, error) {
	r := new(File)
	b, err := os.ReadFile(path)
	if err != nil {
		return r, fmt.Errorf("couldn't load repositories file (%s): %w", path, err)
	}

	err = yaml.Unmarshal(b, r)
	return r, err
}

// Add adds one or more repo entries to a repo file.
func (r *File) Add(re ...*Entry) {
	r.Repositories = append(r.Repositories, re...)
}

// Update attempts to replace one or more repo entries in a repo file. If an
// entry with the same name doesn't exist in the repo file it will add it.
func (r *File) Update(re ...*Entry) {
	for _, target := range re {
		r.update(target)
	}
}

View on GitHub (pinned to 2a29f1770b)

Solutions

Check the expected path: `helm env | grep HELM_CONFIG_HOME`, then inspect <config>/helm/repositories.yaml
Initialize it by adding any repository: `helm repo add stable https://charts.helm.sh/stable` creates the file
Fix directory/file permissions or correct the HELM_CONFIG_HOME value
In code, treat a not-exist error as an empty repo list rather than a fatal failure

Example fix

// before
f, err := repo.LoadFile(path)
if err != nil {
	return err // fails on fresh installs with no repositories.yaml
}

// after
f, err := repo.LoadFile(path)
if err != nil {
	if os.IsNotExist(err) {
		f = repo.NewFile()
	} else {
		return err
	}
}

Defensive patterns

Strategy: validation

Validate before calling

if _, err := os.Stat(path); err != nil {
	if os.IsNotExist(err) {
		return repo.NewFile(), nil // no repositories configured yet - not an error
	}
	return nil, err
}
return repo.LoadFile(path)

Try / catch

f, err := repo.LoadFile(path)
if err != nil {
	if os.IsNotExist(errors.Unwrap(err)) || strings.Contains(err.Error(), "couldn't load repositories file") {
		f = repo.NewFile() // proceed with zero repos
	} else {
		return err
	}
}

Prevention

Stat the file before loading and treat not-exists as an empty repository set
Ensure HELM_CONFIG_HOME is set and writable in containers/CI before first use
Run one `helm repo add` during environment bootstrap so the config file exists

When it happens

Trigger: LoadFile on a host where no repository has ever been added (repositories.yaml never created), HELM_CONFIG_HOME/XDG_CONFIG_HOME pointing to an unreadable path, or file permissions denying read access to the config file.

Common situations: Fresh containers or CI images that never ran `helm repo add`; misconfigured HELM_* environment variables; running as a different user than the one owning the config; cleanup scripts deleting helm config.

Related errors

AI-assisted analysis of helm/helm@2a29f1770b (2026-08-15). Data as JSON: /api/errors/bb91f941b646ff62. Report an issue: GitHub.