{"record":{"id":"60b8d97e2802453f","repo":"docker/compose","slug":"oci-remote-resource-is-disabled-by-q","errorCode":null,"errorMessage":"OCI remote resource is disabled by %q","messagePattern":"OCI remote resource is disabled by %q","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/remote/oci.go","lineNumber":123,"sourceCode":"func (g *ociRemoteLoader) httpTransport(ctx context.Context) http.RoundTripper {\n\tg.transportOnce.Do(func() {\n\t\tg.transport = desktop.ProxyTransportFor(ctx, g.dockerCli.Client())\n\t})\n\treturn g.transport\n}\n\nfunc (g *ociRemoteLoader) Accept(path string) bool {\n\treturn strings.HasPrefix(path, OciPrefix)\n}\n\n//nolint:gocyclo\nfunc (g *ociRemoteLoader) Load(ctx context.Context, path string) (string, error) {\n\tenabled, err := ociRemoteLoaderEnabled()\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\tif !enabled {\n\t\treturn \"\", fmt.Errorf(\"OCI remote resource is disabled by %q\", OCI_REMOTE_ENABLED)\n\t}\n\n\tif g.offline {\n\t\treturn \"\", nil\n\t}\n\n\tlocal, ok := g.known[path]\n\tif !ok {\n\t\tref, err := reference.ParseDockerRef(path[len(OciPrefix):])\n\t\tif err != nil {\n\t\t\treturn \"\", err\n\t\t}\n\n\t\tresolver := oci.NewResolver(g.dockerCli.ConfigFile(), g.httpTransport(ctx), g.insecureRegistries...)\n\n\t\tdescriptor, content, err := oci.Get(ctx, resolver, ref)\n\t\tif err != nil {\n\t\t\treturn \"\", fmt.Errorf(\"failed to pull OCI resource %q: %w\", ref, err)","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/docker/compose/blob/ddc4b044b62e9f715212ea4143fa830fac76382f/pkg/remote/oci.go#L105-L141","documentation":"The OCI remote loader resolves paths with the oci:// prefix by pulling a Compose bundle from an OCI registry. Before doing anything it checks the experimental flag via ociRemoteLoaderEnabled(); when the feature flag is unset, Load refuses to proceed. The %q in the message names the environment variable (COMPOSE_EXPERIMENTAL_OCI_REMOTE) that controls the switch.","triggerScenarios":"Calling loader Load() (or running `docker compose -f oci://...` downstream) with a path starting with the oci:// prefix while the COMPOSE_EXPERIMENTAL_OCI_REMOTE environment variable is not set to a truthy value ('1'/'true'). Accept() returned true because of the prefix, but the gate check then fails.","commonSituations":"Users trying the OCI remote bundle feature on a compose version where it is still gated behind an experiment flag; CI environments that strip env vars; scripts assuming the feature is on by default after seeing docs or blog posts.","solutions":["Set the experiment flag: export COMPOSE_EXPERIMENTAL_OCI_REMOTE=1 (or true) in your shell or compose env file, then rerun.","Verify the variable actually reaches the compose process (check with `docker compose config --environment` or print env in CI) — a missing or misspelled name keeps the loader disabled.","If you do not intend to use OCI remotes, remove the oci:// path from -f/--file arguments and point at a local compose file instead."],"exampleFix":"# before\ndocker compose -f oci://registry.example.com/mybundle up\n# after\nexport COMPOSE_EXPERIMENTAL_OCI_REMOTE=1\ndocker compose -f oci://registry.example.com/mybundle up","handlingStrategy":"validation","validationCode":"// before invoking a loader that accepts oci:// paths\nif strings.HasPrefix(path, \"oci://\") {\n    if os.Getenv(\"COMPOSE_EXPERIMENTAL_OCI_REMOTE\") != \"1\" && os.Getenv(\"COMPOSE_EXPERIMENTAL_OCI_REMOTE\") != \"true\" {\n        return fmt.Errorf(\"set COMPOSE_EXPERIMENTAL_OCI_REMOTE=1 to use OCI remote resources\")\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set COMPOSE_EXPERIMENTAL_OCI_REMOTE=1 in the environment or compose env file whenever oci:// paths are used.","Fail fast in wrapper scripts by checking the env var before calling compose with oci:// paths.","Document the experimental gate in project READMEs so teammates do not hit it on fresh clones."],"tags":["go","docker-compose","oci","feature-flag","configuration"],"backgroundTag":null,"analyzedSha":"ddc4b044b62e9f715212ea4143fa830fac76382f","analyzedAt":"2026-08-15T13:31:42.319Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}