docker/compose · error

cannot publish compose file with local includes

Error message

cannot publish compose file with local includes

What it means

docker compose publish bundles a compose file into an OCI artifact, and an artifact that references includes resolved to local filesystem paths cannot be published self-contained. In cmd/compose/publish.go, after opts.ToProject loads and resolves the project, the loader's metrics count of includes with local sources (metrics.CountIncludesLocal) being > 0 aborts the publish before backend.Publish is called.

Source

Thrown at cmd/compose/publish.go:92

}

func runPublish(ctx context.Context, dockerCli command.Cli, backendOptions *BackendOptions, opts publishOptions, repository string) error {
	if opts.assumeYes {
		backendOptions.Options = append(backendOptions.Options, compose.WithPrompt(compose.AlwaysOkPrompt()))
	}

	backend, err := compose.NewComposeService(dockerCli, backendOptions.Options...)
	if err != nil {
		return err
	}

	project, metrics, err := opts.ToProject(ctx, dockerCli, backend, nil)
	if err != nil {
		return err
	}

	if metrics.CountIncludesLocal > 0 {
		return errors.New("cannot publish compose file with local includes")
	}

	return backend.Publish(ctx, project, repository, api.PublishOptions{
		ResolveImageDigests: opts.resolveImageDigests || opts.app,
		Application:         opts.app,
		OCIVersion:          api.OCIVersion(opts.ociVersion),
		WithEnvironment:     opts.withEnvironment,
		InsecureRegistry:    opts.insecureRegistry,
	})
}

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Inline the included compose files into the main file (merge services, networks, volumes) so no local includes remain.
2. Convert local includes into remote include sources (an OCI reference or URL) so the published artifact can pull them.
3. Build and publish the referenced parts as separate artifacts and reference them by digest from the top-level file.

Example fix

# before (compose.yaml)
include:
  - ./db/compose.yaml

# after: merge db/compose.yaml contents into compose.yaml,
# or reference a published artifact:
include:
  - oci://registry.example.com/myorg/db-stack:1.0

# fail fast if any include resolves to a local path before publish
includes=$(docker compose config --format json 2>/dev/null | jq -r '[.include[]?.path // .include[]?] | length')
if [ "$(docker compose config 2>/dev/null | grep -c 'include:')" -gt 0 ]; then
  echo "local includes cannot be published; inline or remote them first" >&2
  exit 1
fi
docker compose publish "$REPO"

When it happens

Trigger: A compose file with `include: - ./other/compose.yaml` (or any include whose resolved source is a local path), then running `docker compose publish <repository>`. Remote include sources (URLs / OCI references) do not trigger it.

Common situations: Teams splitting a stack into multiple compose files via the include feature and then trying to publish the top-level file; porting a locally-modular project to Docker Hub/registry distribution without inlining the includes.

Related errors

• your Compose stack cannot be published as it only contains a
• use_api_socket can't be used with a Windows Docker Engine
• healthcheck.start_interval requires healthcheck.start_period
• Docker Compose does not support configs.*.driver
• Docker Compose does not support configs.*.template_driver

AI-assisted analysis of docker/compose@ddc4b044b6 (2026-08-15). Data as JSON: /api/errors/0965c750f36babc2. Report an issue: GitHub.