What causes "Failed to parse named repo %q: %v" in hashicorp/nomad?

Fix the image reference in the jobspec/config: lowercase name, at most one tag colon, valid registry path segments.

Failed to parse named repo %q: %v

Error message

Failed to parse named repo %q: %v

What it means

parseRepositoryInfo wraps any failure from reference.ParseNormalizedNamed when normalizing a Docker image repo string (e.g. "nginx", "docker.io/library/nginx:1.25"). It reports the exact repo string plus the underlying parse error, so callers know their image reference was not a valid Docker named reference. This happens before any registry lookup or credential helper is invoked.

Source

Thrown at drivers/docker/utils.go:91

	cfile := new(configfile.ConfigFile)
	if err = cfile.LoadFromReader(f); err != nil {
		return nil, fmt.Errorf("Failed to parse auth config file: %v", err)
	}
	return cfile, nil
}

// repositoryInfo contains the subset of repository metadata needed for auth
// lookup against Docker config files and credential helpers.
type repositoryInfo struct {
	Index *registrytypes.IndexInfo
}

// parseRepositoryInfo takes a repo and returns the repository metadata needed
// for interacting with a Docker config object.
func parseRepositoryInfo(repo string) (*repositoryInfo, error) {
	name, err := reference.ParseNormalizedNamed(repo)
	if err != nil {
		return nil, fmt.Errorf("Failed to parse named repo %q: %v", repo, err)
	}

	domain := reference.Domain(name)
	indexName := normalizeRegistryIndexName(domain)

	repoInfo := &repositoryInfo{
		Index: &registrytypes.IndexInfo{
			Name:     indexName,
			Mirrors:  []string{},
			Secure:   true,
			Official: indexName == dockerRegistryIndexName,
		},
	}

	return repoInfo, nil
}

// firstValidAuth tries a list of auth backends, returning first error or AuthConfiguration

View on GitHub (pinned to 482b49bf1a)

Solutions

Fix the image reference in the jobspec/config: lowercase name, at most one tag colon, valid registry path segments.
Validate the reference locally with `docker pull <repo>` or distribution/reference's ParseNormalizedNamed before submitting the job.
If the name is generated, add interpolation validation so empty/placeholder values never reach the driver.

Example fix

// before
image = "MyApp:1.2:latest"
// after
image = "myregistry.example.com/myteam/myapp:1.2" // or "myapp:1.2"

Defensive patterns

Strategy: validation

Validate before calling

const imageRe = /^[a-z0-9]+((\.|_|__|-+)[a-z0-9]+)*(\/[a-z0-9]+((\.|_|__|-+)[a-z0-9]+))*(:[A-Za-z0-9_.-]+)?(@sha256:[a-f0-9]{64})?$/
if repo === "" || !imageRe.test(repo) {
  return fmt.Errorf("invalid image reference %q before calling driver", repo)
}

Type guard

func isValidRepo(s string) bool { _, err := reference.ParseNormalizedNamed(s); return err == nil }

Try / catch

repoInfo, err := parseRepositoryInfo(repo)
if err != nil {
  return fmt.Errorf("bad image spec in job %q: %w", jobID, err)
}

Prevention

Always lowercase image names and repos.
Keep at most one colon (the tag) unless using @digest.
Validate image strings at job-submission time, not at driver time.

When it happens

Trigger: Calling the docker driver's repository-info helper with a repo string that fails reference.ParseNormalizedNormalizedNamed: invalid characters (uppercase letters, spaces), empty string, more than one colon (e.g. "myrepo:v1:latest"), or a tag+digest combination.

Common situations: Typo'd image names in Nomad job specs (uppercase in image names, e.g. "MyApp:latest"), accidentally pasted registry URLs with ports plus extra colons, template/variable interpolation leaving "{{image}}" or empty strings in the jobspec.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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