What causes "does not match registry specification" in hashicorp/nomad?

Correct the image reference in the job spec to a valid form, e.g. `nginx:1.25` or `my-registry:9090/hello-world:my-tag`

does not match registry specification

Error message

does not match registry specification

What it means

NoPathInImageErr is returned by parseDockerImage when the image string does not match the Docker reference specification regex (reference.ReferenceRegexp), meaning it has no valid repository path. The error text 'does not match registry specification' signals the image reference is malformed for the Docker API.

Source

Thrown at drivers/docker/utils.go:30

	"os/exec"
	"path/filepath"
	"regexp"
	"runtime"
	"strings"

	"github.com/distribution/reference"
	"github.com/docker/cli/cli/config/configfile"
	"github.com/docker/cli/cli/config/types"
	registrytypes "github.com/moby/moby/api/types/registry"
)

const (
	dockerRegistryIndexName   = "docker.io"
	dockerRegistryIndexServer = "https://index.docker.io/v1/"
)

var (
	NoPathInImageErr = errors.New("does not match registry specification")
)

func parseDockerImage(image string) (string, string, error) {
	matches := reference.ReferenceRegexp.FindStringSubmatch(image)
	if matches == nil {
		return "", "", NoPathInImageErr
	}

	repo := matches[1]
	tag := matches[2]
	digest := matches[3]

	if digest == "" {
		if tag == "" {
			tag = "latest"
		}
	} else {
		repo = fmt.Sprintf("%s@%s", repo, digest)

View on GitHub (pinned to 482b49bf1a)

Solutions

Correct the image reference in the job spec to a valid form, e.g. `nginx:1.25` or `my-registry:9090/hello-world:my-tag`
Remove dangling ':' separators or empty segments from the image string
Validate the image string with the Docker CLI (`docker pull <image>`) before deploying
Ensure interpolated variables (e.g. ${IMAGE}) are actually set at job submission

Example fix

// before
config { image = "wrong-docker-image:" }
// after
config { image = "wrong-docker-image:latest" }

Defensive patterns

Strategy: validation

Validate before calling

var refRegexp = regexp.MustCompile(referenceRegexpPattern)
func validImageRef(image string) bool {
    return image != "" && refRegexp.MatchString(image)
}
// call before assigning to job config:
if !validImageRef(image) { return fmt.Errorf("image %q does not match registry specification", image) }

Type guard

func isNoPathInImageErr(err error) bool { return errors.Is(err, NoPathInImageErr) }

Try / catch

repo, tag, err := parseDockerImage(image)
if err != nil {
    if errors.Is(err, NoPathInImageErr) {
        return fmt.Errorf("invalid image reference %q: must include a valid repository path and tag", image)
    }
    return err
}

Prevention

Validate interpolated image variables are non-empty at job submission
Always include an explicit tag or digest in image references
Test image strings with `docker pull` or the reference regex before deploy
Avoid hand-concatenating registry host + image strings

When it happens

Trigger: Calling parseDockerImage (used by the Docker driver when starting a task) with strings like "wrong-docker-image:" (tag separator with no tag) or an empty string, where FindStringSubmatch yields no matches.

Common situations: Typos or trailing colons in job `image` fields; environment-variable-interpolated image names that resolve empty; hand-built image strings missing a tag/digest.

Related errors

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/88239ad31955dfc6. Report an issue: GitHub.