docker/cli · error

compose file contains unsupported options

Error message

compose file contains unsupported options:

%s

What it means

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.

Solutions

1. Read the listed property names and descriptions to see exactly which keys are forbidden.
2. Replace or remove each forbidden property with the supported equivalent (often a Swarm service spec field).
3. Check the Docker Compose spec and your CLI version for the recommended replacement.
4. Validate the compose file with `docker compose config` before `docker stack deploy`.

Example fix

// before: forbidden property present in compose
// (e.g. a v1-only construct)
services:
  web:
    <forbidden_key>: value
// after: remove/replace the forbidden key per the error description
services:
  web:
    <supported_key>: value

// Run the compose loader in a dry-run step and surface forbidden properties before deploy
cfg, err := loadComposeFile(streams, opts)
if err != nil {
    var fpe *loader.ForbiddenPropertiesError
    if errors.As(err, &fpe) {
        // list fpe.Properties to the operator; block deploy
        return fmt.Errorf("fix forbidden properties: %v", fpe.Properties)
    }
    return err
}

// Narrow to ForbiddenPropertiesError to branch handling
var fpe *loader.ForbiddenPropertiesError
if errors.As(err, &fpe) {
    // handle forbidden-properties specifically
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• specify a Compose file (with --compose-file)
• invalid image reference for service
• invalid image reference for service
• unexpected environment variable
• no files specified

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/ab2041356b134926. Report an issue: GitHub.

Appendix: source

Thrown at cli/command/stack/loader.go:35

	"github.com/docker/cli/cli/command"
	"github.com/docker/cli/cli/compose/loader"
	"github.com/docker/cli/cli/compose/schema"
	composetypes "github.com/docker/cli/cli/compose/types"
)

// loadComposeFile parse the composefile specified in the cli and returns its configOptions and version.
func loadComposeFile(streams command.Streams, opts deployOptions) (*composetypes.Config, error) {
	configDetails, err := getConfigDetails(opts.composefiles, streams.In())
	if err != nil {
		return nil, err
	}

	config, err := loader.Load(configDetails)
	if err != nil {
		var fpe *loader.ForbiddenPropertiesError
		if errors.As(err, &fpe) {
			// this error is intentionally formatted multi-line
			return nil, fmt.Errorf("compose file contains unsupported options:\n\n%s\n", propertyWarnings(fpe.Properties)) //nolint:staticcheck // ignore ST1005
		}

		return nil, err
	}

	dicts := getDictsFrom(configDetails.ConfigFiles)
	unsupportedProperties := loader.GetUnsupportedProperties(dicts...)
	if len(unsupportedProperties) > 0 {
		_, _ = fmt.Fprintf(streams.Err(), "Ignoring unsupported options: %s\n\n",
			strings.Join(unsupportedProperties, ", "))
	}

	deprecatedProperties := loader.GetDeprecatedProperties(dicts...)
	if len(deprecatedProperties) > 0 {
		_, _ = fmt.Fprintf(streams.Err(), "Ignoring deprecated options:\n\n%s\n\n",
			propertyWarnings(deprecatedProperties))
	}

View on GitHub (pinned to 4f84911bfe)