{"record":{"id":"99c4ca7707de571b","repo":"docker/compose","slug":"environment-variable-q-required-by-s-q-is-not-s","errorCode":null,"errorMessage":"environment variable %q required by %s %q is not set","messagePattern":"environment variable %q required by (.+?) %q is not set","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/compose/secrets.go","lineNumber":114,"sourceCode":"\t\t\tfiles[i] = types.FileReferenceConfig(config)\n\t\t}\n\t\tfileMap = make(map[string]types.FileObjectConfig)\n\t\tfor k, v := range project.Configs {\n\t\t\tfileMap[k] = types.FileObjectConfig(v)\n\t\t}\n\t}\n\treturn files, fileMap\n}\n\nfunc (s *composeService) resolveFileContent(project *types.Project, source types.FileObjectConfig, mountType mountType) (string, error) {\n\tif source.Content != \"\" {\n\t\t// inlined, or already resolved by include\n\t\treturn source.Content, nil\n\t}\n\tif source.Environment != \"\" {\n\t\tenv, ok := project.Environment[source.Environment]\n\t\tif !ok {\n\t\t\treturn \"\", fmt.Errorf(\"environment variable %q required by %s %q is not set\", source.Environment, mountType, source.Name)\n\t\t}\n\t\treturn env, nil\n\t}\n\treturn \"\", nil\n}\n\nfunc (s *composeService) copyFileToContainer(ctx context.Context, id, content string, file types.FileReferenceConfig) error {\n\tb, err := createTar(content, file)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\t_, err = s.apiClient().CopyToContainer(ctx, id, client.CopyToContainerOptions{\n\t\tDestinationPath: \"/\",\n\t\tContent:         &b,\n\t\tCopyUIDGID:      file.UID != \"\" || file.GID != \"\",\n\t})\n\treturn err","sourceCodeStart":96,"sourceCodeEnd":132,"githubUrl":"https://github.com/docker/compose/blob/ddc4b044b62e9f715212ea4143fa830fac76382f/pkg/compose/secrets.go#L96-L132","documentation":"resolveFileContent reads a secret/config whose value comes from a project environment variable (secrets.<name>.environment). If that variable is absent from project.Environment at container start, compose cannot materialize the value and fails with this error naming the variable, mount type, and resource.","triggerScenarios":"Starting (up/run) a project that declares a secret or config with environment: VAR_NAME where VAR_NAME is unset in the shell, .env file, or environment passed to the compose API.","commonSituations":"Forgetting to export the variable or omitting it from .env; variable names differing between environments (dev vs CI); running compose from a cron/systemd context without the interactive shell's environment.","solutions":["Set the variable before running compose: export VAR_NAME=... or add it to the project .env file.","Check for typos between the environment: key in compose and the actual variable name.","In automation, inject the variable through the API's project environment rather than relying on the shell.","If the value should come from a file instead, switch the definition to file:."],"exampleFix":"# before\nsecrets:\n  api_token:\n    environment: API_TOKEN   # unset\n# $ docker compose up → error\n\n# after\n# .env\nAPI_TOKEN=supersecret\n# $ docker compose up","handlingStrategy":"validation","validationCode":"func envBackedSecretsSet(project *types.Project) error {\n\tcheck := func(m map[string]types.FileObjectConfig, kind string) error {\n\t\tfor name, obj := range m {\n\t\t\tif obj.Environment != \"\" {\n\t\t\t\tif _, ok := project.Environment[obj.Environment]; !ok {\n\t\t\t\t\treturn fmt.Errorf(\"%s %q needs env %s which is unset\", kind, name, obj.Environment)\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\treturn nil\n\t}\n\tif err := check(project.Secrets, \"secret\"); err != nil { return err }\n\treturn check(project.Configs, \"config\")\n}","typeGuard":null,"tryCatchPattern":"if err := compose.Up(ctx, project, opts); err != nil {\n    if strings.Contains(err.Error(), \"required by\") && strings.Contains(err.Error(), \"is not set\") {\n        // extract var name from message, export it or add to .env, retry\n    }\n    return err\n}","preventionTips":["Declare env-backed secrets/configs in .env so they are always present.","List required variables in project documentation and CI env specs.","Fail fast in entrypoint scripts with clear messages when required env is missing."],"tags":["compose","secrets","environment","configuration"],"backgroundTag":null,"analyzedSha":"ddc4b044b62e9f715212ea4143fa830fac76382f","analyzedAt":"2026-08-15T13:31:42.319Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}