{"record":{"id":"2896c3033c3408b4","repo":"docker/compose","slug":"project-name-can-t-be-empty-use-projectname-optio","errorCode":null,"errorMessage":"project name can't be empty. Use ProjectName option to set a valid name","messagePattern":"project name can't be empty\\. Use ProjectName option to set a valid name","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/compose/loader.go","lineNumber":122,"sourceCode":"\t\t// get compose file path set by COMPOSE_FILE\n\t\tcli.WithConfigFileEnv,\n\t\t// if none was selected, get default compose.yaml file from current dir or parent folder\n\t\tcli.WithDefaultConfigPath,\n\t\t// .. and then, a project directory != PWD maybe has been set so let's load .env file\n\t\tcli.WithEnvFiles(options.EnvFiles...), //nolint:gocritic // intentionally applying cli.WithEnvFiles twice.\n\t\tcli.WithDotEnv,                        //nolint:gocritic // intentionally applying cli.WithDotEnv twice.\n\t\t// eventually COMPOSE_PROFILES should have been set\n\t\tcli.WithDefaultProfiles(options.Profiles...),\n\t\tcli.WithName(options.ProjectName),\n\t)\n\n\treturn cli.NewProjectOptions(options.ConfigPaths, append(options.ProjectOptionsFns, opts...)...)\n}\n\n// postProcessProject applies post-loading transformations to the project\nfunc (s *composeService) postProcessProject(project *types.Project, options api.ProjectLoadOptions) (*types.Project, error) {\n\tif project.Name == \"\" {\n\t\treturn nil, errors.New(\"project name can't be empty. Use ProjectName option to set a valid name\")\n\t}\n\n\tproject, err := project.WithServicesEnabled(options.Services...)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\t// Add custom labels\n\tfor name, s := range project.Services {\n\t\ts.CustomLabels = map[string]string{\n\t\t\tapi.ProjectLabel:     project.Name,\n\t\t\tapi.ServiceLabel:     name,\n\t\t\tapi.VersionLabel:     api.ComposeVersion,\n\t\t\tapi.WorkingDirLabel:  project.WorkingDir,\n\t\t\tapi.ConfigFilesLabel: strings.Join(project.ComposeFiles, \",\"),\n\t\t\tapi.OneoffLabel:      \"False\",\n\t\t}\n\t\tif len(options.EnvFiles) != 0 {","sourceCodeStart":104,"sourceCodeEnd":140,"githubUrl":"https://github.com/docker/compose/blob/ddc4b044b62e9f715212ea4143fa830fac76382f/pkg/compose/loader.go#L104-L140","documentation":"After loading a project, postProcessProject asserts that a project name was resolved (from the `name:` field in the compose file, --project-name, COMPOSE_PROJECT_NAME, or the sanitized directory name). An empty name means labels and resource scoping would be broken, so Compose refuses to continue.","triggerScenarios":"cli.NewProjectOptions runs without any name source: no name: in the file, no ProjectName option, no COMPOSE_PROJECT_NAME, and no derivable directory name (e.g. reading config from stdin '-' with an empty/odd directory, or a directory name that sanitizes to empty such as '123' or non-alpha characters).","commonSituations":"Using the Go API with ProjectLoadOptions but forgetting ProjectName and loading from a reader; CI running compose with config piped via stdin; a project directory whose name starts with digits or contains only invalid chars after sanitization; COMPOSE_PROJECT_NAME set to empty string explicitly.","solutions":["Add `name: myproject` to the top of your compose file","Pass `--project-name myproject` on the command line","Export COMPOSE_PROJECT_NAME=myproject in the environment","API users: set ProjectName in api.ProjectLoadOptions before calling the load API"],"exampleFix":"# before\nservices:\n  web:\n    image: nginx\n# after\nname: myproject\nservices:\n  web:\n    image: nginx","handlingStrategy":"validation","validationCode":"# Go API: always set the project name explicitly before loading\nopts := api.ProjectLoadOptions{\n    ProjectName: \"myproject\", // or load from env\n}\n// CLI: ensure one name source exists\n[ -n \"$COMPOSE_PROJECT_NAME\" ] || grep -q '^name:' compose.yaml || echo 'set a project name'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always put `name:` at the top of compose.yaml in repos","When loading config from stdin with the API, pass ProjectName explicitly since directory derivation may not apply"],"tags":["project-name","loader","validation"],"backgroundTag":null,"analyzedSha":"ddc4b044b62e9f715212ea4143fa830fac76382f","analyzedAt":"2026-08-15T13:31:42.319Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}