{"record":{"id":"ab2041356b134926","repo":"docker/cli","slug":"compose-file-contains-unsupported-options-s","errorCode":null,"errorMessage":"compose file contains unsupported options:\n\n%s\n","messagePattern":"compose file contains unsupported options:\n\n(.+?)\n","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/stack/loader.go","lineNumber":35,"sourceCode":"\t\"github.com/docker/cli/cli/command\"\n\t\"github.com/docker/cli/cli/compose/loader\"\n\t\"github.com/docker/cli/cli/compose/schema\"\n\tcomposetypes \"github.com/docker/cli/cli/compose/types\"\n)\n\n// loadComposeFile parse the composefile specified in the cli and returns its configOptions and version.\nfunc loadComposeFile(streams command.Streams, opts deployOptions) (*composetypes.Config, error) {\n\tconfigDetails, err := getConfigDetails(opts.composefiles, streams.In())\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tconfig, err := loader.Load(configDetails)\n\tif err != nil {\n\t\tvar fpe *loader.ForbiddenPropertiesError\n\t\tif errors.As(err, &fpe) {\n\t\t\t// this error is intentionally formatted multi-line\n\t\t\treturn nil, fmt.Errorf(\"compose file contains unsupported options:\\n\\n%s\\n\", propertyWarnings(fpe.Properties)) //nolint:staticcheck // ignore ST1005\n\t\t}\n\n\t\treturn nil, err\n\t}\n\n\tdicts := getDictsFrom(configDetails.ConfigFiles)\n\tunsupportedProperties := loader.GetUnsupportedProperties(dicts...)\n\tif len(unsupportedProperties) > 0 {\n\t\t_, _ = fmt.Fprintf(streams.Err(), \"Ignoring unsupported options: %s\\n\\n\",\n\t\t\tstrings.Join(unsupportedProperties, \", \"))\n\t}\n\n\tdeprecatedProperties := loader.GetDeprecatedProperties(dicts...)\n\tif len(deprecatedProperties) > 0 {\n\t\t_, _ = fmt.Fprintf(streams.Err(), \"Ignoring deprecated options:\\n\\n%s\\n\\n\",\n\t\t\tpropertyWarnings(deprecatedProperties))\n\t}\n","sourceCodeStart":17,"sourceCodeEnd":53,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/stack/loader.go#L17-L53","documentation":"Raised by loadComposeFile when the Compose loader returns a ForbiddenPropertiesError, meaning the compose file uses options that Docker CLI explicitly forbids (not merely deprecated/unsupported, but rejected). The error lists each forbidden property with its description.","triggerScenarios":"Loading a compose file whose top-level or service keys include a property flagged as forbidden by the loader's ForbiddenProperties map (e.g. removed v1-only constructs or options Docker refuses to translate). The error at loader.go:35 formats fpe.Properties via propertyWarnings.","commonSituations":"Migrating an old docker-compose v1/v2 file to a Swarm stack deploy; using a Compose feature that exists in compose v2 but is forbidden by the Docker CLI stack loader; copy-pasting config from docs targeting a different tool version.","solutions":["Read the listed property names and descriptions to see exactly which keys are forbidden.","Replace or remove each forbidden property with the supported equivalent (often a Swarm service spec field).","Check the Docker Compose spec and your CLI version for the recommended replacement.","Validate the compose file with `docker compose config` before `docker stack deploy`."],"exampleFix":"// before: forbidden property present in compose\n// (e.g. a v1-only construct)\nservices:\n  web:\n    <forbidden_key>: value\n// after: remove/replace the forbidden key per the error description\nservices:\n  web:\n    <supported_key>: value","handlingStrategy":"validation","validationCode":"// Run the compose loader in a dry-run step and surface forbidden properties before deploy\ncfg, err := loadComposeFile(streams, opts)\nif err != nil {\n    var fpe *loader.ForbiddenPropertiesError\n    if errors.As(err, &fpe) {\n        // list fpe.Properties to the operator; block deploy\n        return fmt.Errorf(\"fix forbidden properties: %v\", fpe.Properties)\n    }\n    return err\n}","typeGuard":"// Narrow to ForbiddenPropertiesError to branch handling\nvar fpe *loader.ForbiddenPropertiesError\nif errors.As(err, &fpe) {\n    // handle forbidden-properties specifically\n}","tryCatchPattern":null,"preventionTips":["Run `docker compose config` as a CI gate before `docker stack deploy`.","Keep compose files on a supported version for your CLI.","Track the forbidden-properties list for your CLI version."],"tags":["docker","stack","compose","loader","forbidden","validation"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}