spf13/viper · error

missing configuration for 'configPath'

Error message

missing configuration for 'configPath'

What it means

Returned by Viper.SafeWriteConfig (viper.go:1702-1707) when len(v.configPaths) < 1. SafeWriteConfig builds the target path as filepath.Join(configPaths[0], configName+"."+configType), so it requires at least one AddConfigPath call. Note AddConfigPath is a logged no-op when a custom Finder is set (viper.go:438-441), so configPaths stays empty in that case.

Source

Thrown at viper.go:1704

// WriteConfig writes the current configuration to a file.
func WriteConfig() error { return v.WriteConfig() }

// WriteConfig writes the current configuration to a file.
func (v *Viper) WriteConfig() error {
	filename, err := v.getConfigFile()
	if err != nil {
		return err
	}
	return v.writeConfig(filename, true)
}

// SafeWriteConfig writes current configuration to file only if the file does not exist.
func SafeWriteConfig() error { return v.SafeWriteConfig() }

// SafeWriteConfig writes current configuration to file only if the file does not exist.
func (v *Viper) SafeWriteConfig() error {
	if len(v.configPaths) < 1 {
		return errors.New("missing configuration for 'configPath'")
	}
	return v.SafeWriteConfigAs(filepath.Join(v.configPaths[0], v.configName+"."+v.configType))
}

// WriteConfigAs writes current configuration to a given filename.
func WriteConfigAs(filename string) error { return v.WriteConfigAs(filename) }

// WriteConfigAs writes current configuration to a given filename.
func (v *Viper) WriteConfigAs(filename string) error {
	return v.writeConfig(filename, true)
}

// WriteConfigTo writes current configuration to an [io.Writer].
func WriteConfigTo(w io.Writer) error { return v.WriteConfigTo(w) }

// WriteConfigTo writes current configuration to an [io.Writer].
func (v *Viper) WriteConfigTo(w io.Writer) error {
	format := strings.ToLower(v.getConfigType())

View on GitHub (pinned to 528f7416c4)

Solutions

1. Call v.AddConfigPath("/etc/myapp") (or similar) before v.SafeWriteConfig().
2. If you use a custom Finder, switch to v.SafeWriteConfigAs("/etc/myapp/config.yaml") which takes an explicit absolute path and ignores configPaths.
3. Ensure configType and configName are also set so the joined filename is valid.

Example fix

// before
v := New()
v.SetConfigName("app")
v.SetConfigType("yaml")
_ = v.SafeWriteConfig() // -> missing configuration for 'configPath'

// after
v := New()
v.SetConfigName("app")
v.SetConfigType("yaml")
v.AddConfigPath("/etc/myapp")
_ = v.SafeWriteConfig()

// alt for custom finder users
_ = v.SafeWriteConfigAs("/etc/myapp/app.yaml")

// configPaths is unexported; the only way to populate it is AddConfigPath.
// Validate by ensuring you call AddConfigPath, or skip SafeWriteConfig entirely.
v.AddConfigPath("/etc/myapp") // required before SafeWriteConfig
v.SetConfigName("app")
v.SetConfigType("yaml")

// If using a custom Finder (which makes AddConfigPath a no-op), prefer:
//   err := v.SafeWriteConfigAs("/etc/myapp/app.yaml")

if err := v.SafeWriteConfig(); err != nil {
    if strings.Contains(err.Error(), "missing configuration for 'configPath'") {
        // fall back to an explicit path
        err = v.SafeWriteConfigAs("/etc/myapp/app.yaml")
    }
}

When it happens

Trigger: Calling v.SafeWriteConfig() without any prior v.AddConfigPath(...), or after setting a custom finder (NewWithOptions(WithFinder(f)) / v.SetFinder(f)) which makes AddConfigPath ineffective.

Common situations: Migrated to finder-based config discovery but kept SafeWriteConfig in a bootstrap/init path; test helpers that forget to AddConfigPath; init code that calls SafeWriteConfig before any path setup.

Related errors

• encoder not found for this format
• cannot decode configuration: unable to determine config type
• config type could not be determined for %s

AI-assisted analysis of spf13/viper@528f7416c4 (2026-08-04). Data as JSON: /data/errors/b2b3f9cd28bd5b03.json. Report an issue: GitHub.