{"record":{"id":"49ea1107298a8e1d","repo":"docker/cli","slug":"invalid-environment-variable-val","errorCode":null,"errorMessage":"invalid environment variable: {val}","messagePattern":"invalid environment variable: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"opts/env.go","lineNumber":21,"sourceCode":"import (\n\t\"errors\"\n\t\"os\"\n\t\"strings\"\n)\n\n// ValidateEnv validates an environment variable and returns it.\n// If no value is specified, it obtains its value from the current environment.\n//\n// Environment variable names are not validated, and it's up to the application\n// inside the container to validate them (see [moby-16585]). The only validation\n// here is to check if name is empty, per [moby-25099].\n//\n// [moby-16585]: https://github.com/moby/moby/issues/16585\n// [moby-25099]: https://github.com/moby/moby/issues/25099\nfunc ValidateEnv(val string) (string, error) {\n\tk, _, hasValue := strings.Cut(val, \"=\")\n\tif k == \"\" {\n\t\treturn \"\", errors.New(\"invalid environment variable: \" + val)\n\t}\n\tif hasValue {\n\t\t// val contains a \"=\" (but value may be an empty string)\n\t\treturn val, nil\n\t}\n\tif envVal, ok := os.LookupEnv(k); ok {\n\t\treturn k + \"=\" + envVal, nil\n\t}\n\treturn val, nil\n}\n","sourceCodeStart":3,"sourceCodeEnd":32,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/opts/env.go#L3-L32","documentation":"Returned by ValidateEnv (opts/env.go:21) when the environment variable string has an empty key — the part before '=' is empty. Per the code comments (moby-25099), only the emptiness of the key is checked; the key name itself is not otherwise validated, as that is deferred to the container application (moby-16585). If no '=' is present and the key is non-empty, the value is looked up from the host environment.","triggerScenarios":"ValidateEnv is called with a string where strings.Cut on '=' yields an empty key — e.g., '=value' (key before = is empty), or an empty string ''. ValidateEnv(\"=FOO\") or ValidateEnv(\"\") both trigger this.","commonSituations":"Malformed -e flag with a leading '=' (e.g., -e =PATH), empty environment variable string from shell expansion of an unset variable, or a programmatic error building the env list.","solutions":["Ensure the environment variable string starts with a non-empty key before any '=' sign.","If passing KEY without a value (to inherit from host env), ensure the key name is present and non-empty.","Check for stray '=' at the start of -e arguments."],"exampleFix":"// before: empty key\n// docker run -e =PATH nginx\n\n// after: valid key\n// docker run -e PATH nginx\n// or with explicit value:\n// docker run -e PATH=/usr/bin nginx","handlingStrategy":"validation","validationCode":"func validateEnvKey(val string) error {\n    k, _, _ := strings.Cut(val, \"=\")\n    if k == \"\" {\n        return fmt.Errorf(\"environment variable must have a non-empty key: %q\", val)\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"if _, err := opts.ValidateEnv(val); err != nil {\n    if strings.Contains(err.Error(), \"invalid environment variable\") {\n        return fmt.Errorf(\"bad env var %q: key before '=' must not be empty\", val)\n    }\n    return err\n}","preventionTips":["Ensure environment variable strings have a non-empty key before any '='.","Check for stray leading '=' characters in -e flag values.","Validate env var lists from configuration files before passing to ValidateEnv."],"tags":["env","validation","environment-variable"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}