docker/compose · error

COMPOSE_EXPERIMENTAL_GIT_REMOTE environment variable expects

Error message

COMPOSE_EXPERIMENTAL_GIT_REMOTE environment variable expects boolean value: %w

What it means

`COMPOSE_EXPERIMENTAL_GIT_REMOTE` gates the `oci://`-style git remote include loader. Its value is parsed with `strconv.ParseBool`; anything not in {1,t,T,TRUE,true,True,0,f,F,FALSE,false,False} fails and this error wraps the parse failure.

Source

Thrown at pkg/remote/git.go:47

	"strings"

	"github.com/compose-spec/compose-go/v2/cli"
	"github.com/compose-spec/compose-go/v2/loader"
	"github.com/compose-spec/compose-go/v2/types"
	"github.com/docker/cli/cli/command"
	gitutil "github.com/moby/buildkit/frontend/dockerfile/dfgitutil"
	"github.com/sirupsen/logrus"

	"github.com/docker/compose/v5/pkg/api"
)

const GIT_REMOTE_ENABLED = "COMPOSE_EXPERIMENTAL_GIT_REMOTE"

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

func NewGitRemoteLoader(dockerCli command.Cli, offline bool) loader.ResourceLoader {
	return gitRemoteLoader{
		dockerCli: dockerCli,
		offline:   offline,
		known:     map[string]string{},
	}
}

type gitRemoteLoader struct {
	dockerCli command.Cli
	offline   bool
	known     map[string]string

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Set the variable to a valid Go boolean, e.g. `COMPOSE_EXPERIMENTAL_GIT_REMOTE=true`
2. Unset the variable entirely — an empty value defaults the feature to enabled
3. Audit shell scripts and CI secrets for values like yes/no/on/off

Example fix

# before
export COMPOSE_EXPERIMENTAL_GIT_REMOTE=yes

# after
export COMPOSE_EXPERIMENTAL_GIT_REMOTE=true

# bash: fail fast on non-boolean experimental flags
v="${COMPOSE_EXPERIMENTAL_GIT_REMOTE:-}"
[ -z "$v" ] || [ "$v" = "0" ] || [ "$v" = "1" ] || { case "${v,,}" in true|false) ;; *) echo "bad bool: $v" >&2; exit 1;; esac; }

When it happens

Trigger: Setting the env var to values like `yes`, `on`, `enable`, or `True ` (with whitespace) and running any compose command that initializes the remote resource loader.

Common situations: Scripts using `export COMPOSE_EXPERIMENTAL_GIT_REMOTE=yes`; CI env matrices quoting values oddly; users assuming on/off semantics instead of Go booleans.

Related errors

• COMPOSE_EXPERIMENTAL_OCI_REMOTE environment variable expects
• cannot combine %s and --remove-orphans
• environment variable %q required by %s %q is not set
• service %s doesn't have a build section, can't apply %s on w
• can't watch with action %q on service %s without a command

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