docker/compose · error

git remote resource is disabled by %q

Error message

git remote resource is disabled by %q

What it means

The git remote loader refuses to resolve an include whose path parses as a git ref when `COMPOSE_EXPERIMENTAL_GIT_REMOTE` is explicitly set to a falsy boolean. It is the intentional 'feature off' error, returned from `gitRemoteLoader.Load`.

Source

Thrown at pkg/remote/git.go:81

	dockerCli command.Cli
	offline   bool
	known     map[string]string
}

func (g gitRemoteLoader) Accept(path string) bool {
	_, _, err := gitutil.ParseGitRef(path)
	return err == nil
}

var commitSHA = regexp.MustCompile(`^[a-f0-9]{40}$`)

func (g gitRemoteLoader) Load(ctx context.Context, path string) (string, error) {
	enabled, err := gitRemoteLoaderEnabled()
	if err != nil {
		return "", err
	}
	if !enabled {
		return "", fmt.Errorf("git remote resource is disabled by %q", GIT_REMOTE_ENABLED)
	}

	ref, _, err := gitutil.ParseGitRef(path)
	if err != nil {
		return "", err
	}

	local, ok := g.known[path]
	if !ok {
		if ref.Ref == "" {
			ref.Ref = "HEAD" // default branch
		}

		err = g.resolveGitRef(ctx, path, ref)
		if err != nil {
			return "", err
		}

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Enable the feature: `export COMPOSE_EXPERIMENTAL_GIT_REMOTE=true`
2. Remove the git remote include and vendor the file locally if the feature must stay off

Example fix

# before
export COMPOSE_EXPERIMENTAL_GIT_REMOTE=false
# compose.yaml has: include: [{path: git://github.com/org/repo.git#main}] 

# after
export COMPOSE_EXPERIMENTAL_GIT_REMOTE=true

# refuse to run when git includes are needed but the feature is off
if grep -q 'git://' compose*.yaml 2>/dev/null && [ "${COMPOSE_EXPERIMENTAL_GIT_REMOTE:-}" = "false" ]; then
  echo "project needs git remote includes; unset or set true" >&2; exit 1
fi

When it happens

Trigger: A compose file uses an include like `include: [{path: git://...}]` (or another ParseGitRef-recognized form) while `COMPOSE_EXPERIMENTAL_GIT_REMOTE=false` is exported in the environment.

Common situations: Teams disabling experimental features in CI or hardened environments; stale env settings from older Compose versions where the feature was opt-in and a project still uses git includes.

Related errors

• repository does not contain ref %s, output: %q: %w
• COMPOSE_EXPERIMENTAL_GIT_REMOTE environment variable expects
• initializing remote resource cache: %w
• git subdirectory must be relative, got: %s
• git subdirectory path traversal detected: %s

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