COMPOSE_EXPERIMENTAL_OCI_REMOTE environment variable expects

Error message

COMPOSE_EXPERIMENTAL_OCI_REMOTE environment variable expects boolean value: %w

What it means

`COMPOSE_EXPERIMENTAL_OCI_REMOTE` gates the `oci://` include loader. Its value is parsed with `strconv.ParseBool`, so any non-boolean string (yes, on, 1.0, 'true ' with whitespace) fails and this error wraps the underlying parse error.

Source

Thrown at pkg/remote/oci.go:77

	targetDir := filepath.Dir(targetPath)

	// Clean both paths to resolve any .. or . components
	cleanBase := filepath.Clean(base)
	cleanTargetDir := filepath.Clean(targetDir)

	// Check if the target directory is the same as base directory
	if cleanTargetDir != cleanBase {
		return fmt.Errorf("invalid OCI artifact")
	}

	return nil
}

func ociRemoteLoaderEnabled() (bool, error) {
	if v := os.Getenv(OCI_REMOTE_ENABLED); v != "" {
		enabled, err := strconv.ParseBool(v)
		if err != nil {
			return false, fmt.Errorf("COMPOSE_EXPERIMENTAL_OCI_REMOTE environment variable expects boolean value: %w", err)
		}
		return enabled, err
	}
	return true, nil
}

func NewOCIRemoteLoader(dockerCli command.Cli, offline bool, options api.OCIOptions) loader.ResourceLoader {
	return &ociRemoteLoader{
		dockerCli:          dockerCli,
		offline:            offline,
		known:              map[string]string{},
		insecureRegistries: options.InsecureRegistries,
	}
}

type ociRemoteLoader struct {
	dockerCli          command.Cli
	offline            bool

View on GitHub (pinned to ddc4b044b6)

Solutions

Use a strict Go boolean: `COMPOSE_EXPERIMENTAL_OCI_REMOTE=true` (or `false` to disable)
Unset the variable — empty means the feature defaults to enabled
Search shell profiles, Makefiles, and CI variables for informal boolean spellings

Example fix

# before
export COMPOSE_EXPERIMENTAL_OCI_REMOTE=on

# after
export COMPOSE_EXPERIMENTAL_OCI_REMOTE=true

Defensive patterns

Strategy: validation

Validate before calling

# fail fast on non-boolean OCI flag values
v="${COMPOSE_EXPERIMENTAL_OCI_REMOTE:-}"
[ -z "$v" ] || { case "$v" in true|false|TRUE|FALSE|True|False|1|0|t|f|T|F) ;; *) echo "COMPOSE_EXPERIMENTAL_OCI_REMOTE must be a boolean" >&2; exit 1;; esac; }

Prevention

Use true/false literals for all COMPOSE_EXPERIMENTAL_* env flags
Remember empty/unset means enabled by default — usually you can just delete the variable

When it happens

Trigger: Exporting the variable with a non-Go-boolean value and running any compose command that constructs the remote loader (any command parsing the project when oci:// includes may exist).

Common situations: CI pipelines using yes/no conventions; env files with quoted or padded values; scripts written before the feature defaulted to on, setting it to informal truthy strings.

Related errors

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