docker pull/push rejects IPv6 link-local literal with zone ID ([fe80::...%eth0]:5000/image): "invalid reference format"

Open
  • Is something wrong?
#53,816 2 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
68/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Active
Tech stack
docker, go
Domain
networking

Research direction

Start with the reference parser that rejects the IPv6 literal, using the reproduced docker pull command as the failing case. Then inspect the registry client’s URL construction for zone-ID handling and verify that the reference is accepted and the zone ID is percent-encoded when connecting to the registry.

Written by the indexing model from the issue text.

Description

kind/bug
Description

IPv6 address literals in image references are accepted since the fix from distribution/distribution#3489 (see #39033), e.g. [::1]:5000/image. However, a link-local IPv6 address with a zone ID is still rejected by the reference parser, so it is impossible to push/pull to a registry reachable only via IPv6 link-local.

Use case: several devices on a network with only static link-local IPv6. One device runs an OCI registry (registry:3, host networking, listening on *:5000), the others need to pull/push. Global/ULA addresses are not available.

The error comes from the reference parser, before any network connection is attempted. The registry itself is reachable over link-local (curl works, see below).

Reproduce
  1. Run a registry on the host: docker run -d --network host registry:3
  2. Run:

$ docker pull '[fe80::215:5dff:fea0:7253%eth0]:5000/test:latest'
invalid reference format

Image
Expected behavior

The reference is accepted and the client connects to https://[fe80::...%25eth0]:5000/v2/ (zone ID percent-encoded per RFC 6874), or a documented alternative syntax exists for link-local registries.

docker version
29.8.1 / 29.8.1
docker info
docker info
Client: Docker Engine - Community
 Version:    29.8.1
 Context:    default
 Debug Mode: false
 Plugins:
  buildx: Docker Buildx (Docker Inc.)
    Version:  v0.37.1
    Path:     /usr/libexec/docker/cli-plugins/docker-buildx
  compose: Docker Compose (Docker Inc.)
    Version:  v5.5.1
    Path:     /usr/libexec/docker/cli-plugins/docker-compose

Server:
 Containers: 4
  Running: 2
  Paused: 0
  Stopped: 2
 Images: 8
 Server Version: 29.8.1
 Storage Driver: overlay2
  Backing Filesystem: extfs
  Supports d_type: true
  Using metacopy: false
  Native Overlay Diff: true
  userxattr: false
 Logging Driver: json-file
 Cgroup Driver: systemd
 Cgroup Version: 2
 Plugins:
  Volume: local
Additional Info

Suggested direction: allow an optional zone ID in the IPv6 literal of the reference domain regexp (e.g. [fe80::1%25eth0]) and make sure the registry client percent-encodes it when building the URL (Go's net/url and net.Dialer handle zone IDs). If out of scope, a docs note that link-local zone IDs are unsupported would help.

Dominant language
Go
Stars
72.2k
Forks
19.3k
Avg merge
1d 18h
Merged PRs (30d)
157

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from moby/moby

All issues in moby/moby

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.