{"id":"21ab4f1ed30d0aac","repo":"spf13/viper","slug":"flag-for-q-is-nil","errorCode":null,"errorMessage":"flag for %q is nil","messagePattern":"flag for %q is nil","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"viper.go","lineNumber":1109,"sourceCode":"func (v *Viper) BindPFlags(flags *pflag.FlagSet) error {\n\treturn v.BindFlagValues(pflagValueSet{flags})\n}\n\n// BindPFlag binds a specific key to a pflag (as used by cobra).\n// Example (where serverCmd is a Cobra instance):\n//\n//\tserverCmd.Flags().Int(\"port\", 1138, \"Port to run Application server on\")\n//\tViper.BindPFlag(\"port\", serverCmd.Flags().Lookup(\"port\"))\nfunc BindPFlag(key string, flag *pflag.Flag) error { return v.BindPFlag(key, flag) }\n\n// BindPFlag binds a specific key to a pflag (as used by cobra).\n// Example (where serverCmd is a Cobra instance):\n//\n//\tserverCmd.Flags().Int(\"port\", 1138, \"Port to run Application server on\")\n//\tViper.BindPFlag(\"port\", serverCmd.Flags().Lookup(\"port\"))\nfunc (v *Viper) BindPFlag(key string, flag *pflag.Flag) error {\n\tif flag == nil {\n\t\treturn fmt.Errorf(\"flag for %q is nil\", key)\n\t}\n\treturn v.BindFlagValue(key, pflagValue{flag})\n}\n\n// BindFlagValues binds a full FlagValue set to the configuration, using each flag's long\n// name as the config key.\nfunc BindFlagValues(flags FlagValueSet) error { return v.BindFlagValues(flags) }\n\n// BindFlagValues binds a full FlagValue set to the configuration, using each flag's long\n// name as the config key.\nfunc (v *Viper) BindFlagValues(flags FlagValueSet) (err error) {\n\tflags.VisitAll(func(flag FlagValue) {\n\t\tif err = v.BindFlagValue(flag.Name(), flag); err != nil {\n\t\t\treturn\n\t\t}\n\t})\n\treturn nil\n}","sourceCodeStart":1091,"sourceCodeEnd":1127,"githubUrl":"https://github.com/spf13/viper/blob/528f7416c4b56a4948673984b190bf8713f0c3c4/viper.go#L1091-L1127","documentation":"Returned by Viper.BindPFlag (viper.go:1107-1110) when the passed *pflag.Flag is nil. The nil almost always comes from pflag.FlagSet.Lookup(name), which returns nil for a flag that is not defined on that set.","triggerScenarios":"v.BindPFlag(\"port\", cmd.Flags().Lookup(\"port\")) where 'port' was never added to cmd.Flags(); typo in the flag name; binding before the flag is registered; looking up on the wrong FlagSet (LocalFlags vs PersistentFlags).","commonSituations":"Cobra app where the flag lives on PersistentFlags but Lookup is called on LocalFlags; refactor that renamed a flag but left the old string in BindPFlag; binding inside an init() that runs before flag registration.","solutions":["Nil-check the Lookup result before binding: if f := flags.Lookup(\"port\"); f != nil { v.BindPFlag(\"port\", f) }.","Register the flag first (e.g. cmd.Flags().Int(\"port\", 8080, \"...\")) before calling BindPFlag.","Look up on the correct FlagSet — PersistentFlags() for inherited flags, Flags() for local."],"exampleFix":"// before\nv.BindPFlag(\"port\", cmd.Flags().Lookup(\"port\")) // -> flag for \"port\" is nil\n\n// after\nif f := cmd.Flags().Lookup(\"port\"); f != nil {\n    _ = v.BindPFlag(\"port\", f)\n} else {\n    // flag not defined; register it or log the misconfiguration\n}","handlingStrategy":"type-guard","validationCode":"func bindFlag(v *viper.Viper, key string, flags *pflag.FlagSet, name string) error {\n    f := flags.Lookup(name)\n    if f == nil {\n        return fmt.Errorf(\"flag %q not defined on the FlagSet\", name)\n    }\n    return v.BindPFlag(key, f)\n}","typeGuard":"// nil-guard for *pflag.Flag before binding\nfunc isFlagBoundable(f *pflag.Flag) bool { return f != nil }\n\n// usage\nif f := cmd.Flags().Lookup(\"port\"); isFlagBoundable(f) {\n    _ = v.BindPFlag(\"port\", f)\n}","tryCatchPattern":"if err := v.BindPFlag(\"port\", cmd.Flags().Lookup(\"port\")); err != nil {\n    if strings.Contains(err.Error(), \"is nil\") {\n        // flag not registered or looked up on the wrong FlagSet\n    }\n}","preventionTips":["Always nil-check pflag FlagSet.Lookup results before binding.","Register flags before any BindPFlag call (watch init() ordering).","Look up inherited flags on PersistentFlags(), local ones on Flags()."],"tags":["flags","pflag","binding","cobra"],"analyzedSha":"528f7416c4b56a4948673984b190bf8713f0c3c4","analyzedAt":"2026-08-04T21:46:12.352Z","schemaVersion":2}