What causes "failed to expand configuration path" in golangci/golangci-lint?

Set the HOME environment variable to a readable directory.

failed to expand configuration path

Error message

failed to expand configuration path

What it means

After the mutual-exclusion check, evaluateOptions expands a leading `~/` in the --config path via homedir.Expand. If expansion fails (bad home-directory resolution), the loader returns this error instead of proceeding with an unusable path.

Source

Thrown at pkg/config/base_loader.go:94

	} else {
		l.setupConfigFileSearch()
	}

	return nil
}

func (l *BaseLoader) evaluateOptions() (string, error) {
	if l.opts.NoConfig && l.opts.Config != "" {
		return "", errors.New("can't combine option --config and --no-config")
	}

	if l.opts.NoConfig {
		return "", errConfigDisabled
	}

	configFile, err := homedir.Expand(l.opts.Config)
	if err != nil {
		return "", errors.New("failed to expand configuration path")
	}

	return configFile, nil
}

func (l *BaseLoader) setupConfigFileSearch() {
	l.viper.SetConfigName(".golangci")

	configSearchPaths := l.getConfigSearchPaths()

	l.log.Infof("Config search paths: %s", configSearchPaths)

	for _, p := range configSearchPaths {
		l.viper.AddConfigPath(p)
	}
}

func (l *BaseLoader) getConfigSearchPaths() []string {

View on GitHub (pinned to ed7a235d2d)

Solutions

Set the HOME environment variable to a readable directory.
Replace `~` in the --config value with the absolute path (e.g. /root/.golangci.yml).
In code, validate/expand the path with os.UserHomeDir or filepath.Abs before setting opts.Config.

Example fix

// before
golangci-lint run --config ~/.golangci.yml   # HOME unset in CI

// after
export HOME=/root
golangci-lint run --config /root/.golangci.yml

Defensive patterns

Strategy: validation

Validate before calling

const path = require('path');
function resolveConfig(p) {
  if (p.startsWith('~')) {
    const home = process.env.HOME;
    if (!home) throw new Error('HOME is not set; cannot expand ~ in config path');
    return path.join(home, p.slice(1));
  }
  return p;
}

Prevention

Use absolute config paths in CI scripts and Dockerfiles.
Ensure HOME is set in container/cron environments.
Check the file exists (fs.existsSync / test -f) before invoking the linter.

When it happens

Trigger: Passing a config path starting with `~` while the HOME environment variable is unset/empty, or any path homedir.Expand cannot resolve on the current OS/user context.

Common situations: CI containers without HOME set (e.g. minimal Docker images, cron jobs with a stripped environment); running under service accounts with no home directory.

Related errors

AI-assisted analysis of golangci/golangci-lint@ed7a235d2d (2026-09-02). Data as JSON: /api/errors/b57e82c75f286869. Report an issue: GitHub.