oauth2-proxy/oauth2-proxy · error

unable to register flags: %w

Error message

unable to register flags: %w

What it means

Wrap error in options.Load: reflectively registering config/flags onto the target options struct failed. Per the adjacent comment this should only happen on a programming error (struct field missing required cfg/flag tags), not from user input.

Source

Thrown at pkg/apis/options/load.go:45

func Load(configFileName string, flagSet *pflag.FlagSet, into interface{}) error {
	v := viper.New()
	v.SetConfigFile(configFileName)
	v.SetConfigType("toml") // Config is in toml format
	v.SetEnvPrefix("OAUTH2_PROXY")
	v.AutomaticEnv()
	v.SetTypeByDefaultValue(true)

	if configFileName != "" {
		err := v.ReadInConfig()
		if err != nil {
			return fmt.Errorf("unable to load config file: %w", err)
		}
	}

	err := registerFlags(v, "", flagSet, into)
	if err != nil {
		// This should only happen if there is a programming error
		return fmt.Errorf("unable to register flags: %w", err)
	}

	// UnmarshalExact will return an error if the config includes options that are
	// not mapped to fields of the into struct
	err = v.UnmarshalExact(into, decodeFromCfgTag)
	if err != nil {
		return fmt.Errorf("error unmarshalling config: %w", err)
	}

	return nil
}

// LoadYAML will load a YAML based configuration file into the options interface provided.
func LoadYAML(configFileName string, opts interface{}) error {
	buffer, err := loadAndSubstituteEnvs(configFileName)
	if err != nil {
		return err
	}

View on GitHub (pinned to 33c2eb92de)

Solutions

1. Treat as a developer error: verify newly added Options fields have both cfg and flag tags
2. Revert recent changes to the options structs if this appears after an upgrade
3. Check nested struct fields carry the ,squash cfg tag

When it happens

Trigger: Thrown at pkg/apis/options/load.go:45 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of oauth2-proxy/oauth2-proxy@33c2eb92de (2026-09-06). Data as JSON: /api/errors/246c1a03ce7f3797. Report an issue: GitHub.