spf13/viper · error

missing key to bind to

Error message

missing key to bind to

What it means

Returned by Viper.BindEnv (viper.go:1155-1158) when len(input) == 0. BindEnv is variadic (input ...string) and treats input[0] as the config key; calling it with zero arguments has no key to bind and is rejected.

Source

Thrown at viper.go:1157

}

// BindEnv binds a Viper key to a ENV variable.
// ENV variables are case sensitive.
// If only a key is provided, it will use the env key matching the key, uppercased.
// If more arguments are provided, they will represent the env variable names that
// should bind to this key and will be taken in the specified order.
// EnvPrefix will be used when set when env name is not provided.
func BindEnv(input ...string) error { return v.BindEnv(input...) }

// BindEnv binds a Viper key to a ENV variable.
// ENV variables are case sensitive.
// If only a key is provided, it will use the env key matching the key, uppercased.
// If more arguments are provided, they will represent the env variable names that
// should bind to this key and will be taken in the specified order.
// EnvPrefix will be used when set when env name is not provided.
func (v *Viper) BindEnv(input ...string) error {
	if len(input) == 0 {
		return fmt.Errorf("missing key to bind to")
	}

	key := strings.ToLower(input[0])

	if len(input) == 1 {
		v.env[key] = append(v.env[key], v.mergeWithEnvPrefix(key))
	} else {
		v.env[key] = append(v.env[key], input[1:]...)
	}

	return nil
}

// MustBindEnv wraps BindEnv in a panic.
// If there is an error binding an environment variable, MustBindEnv will
// panic.
func MustBindEnv(input ...string) { v.MustBindEnv(input...) }

View on GitHub (pinned to 528f7416c4)

Solutions

1. Always pass at least the key: v.BindEnv("DATABASE_URL").
2. If forwarding a variadic slice, guard with if len(args) > 0 before calling BindEnv.
3. Use errors.Is on the returned error to surface a clear message in helpers.

Example fix

// before
v.BindEnv() // -> missing key to bind to

// after
v.BindEnv("database.url")
// optional second arg is the explicit env var name:
v.BindEnv("database.url", "DB_DSN")

func bindEnvSafe(v *viper.Viper, args ...string) error {
    if len(args) == 0 {
        return errors.New("BindEnv requires at least the config key")
    }
    return v.BindEnv(args...)
}

if err := v.BindEnv(keys...); err != nil {
    if errors.Is(err, /* viper does not export this sentinel; match by string */) nil {
        // no key supplied
    }
    if strings.Contains(err.Error(), "missing key to bind to") {
        // caller passed an empty key list
    }
}

When it happens

Trigger: Calling v.BindEnv() with no arguments; forwarding an empty slice via v.BindEnv(keys...) where keys is empty; helper code that conditionally builds the arg list but ends up with none.

Common situations: Refactor that moved the key into a separately-computed slice which can be empty; wrapper that calls BindEnv(configKeys...) without ensuring at least one entry; copy-paste dropping the literal key.

Related errors

• error while binding environment variable: %v
• flag for %q is nil

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