hashicorp/nomad · error

Failed to find docker auth for repo %q: %v

Error message

Failed to find docker auth for repo %q: %v

What it means

pullImage fails when resolveRegistryAuthentication cannot find credentials for the image repository and AuthSoftFail is not set. Docker requires auth for private registries, so without credentials the pull cannot proceed. This is thrown before any network pull is attempted.

Source

Thrown at drivers/docker/driver.go:661

	}

	// Load the image if specified
	if driverConfig.LoadImage != "" {
		return d.loadImage(task, driverConfig, client)
	}

	// Download the image
	return d.pullImage(task, driverConfig, repo, tag)
}

// pullImage creates an image by pulling it from a docker registry
func (d *Driver) pullImage(task *drivers.TaskConfig, driverConfig *TaskConfig, repo, tag string) (id, user string, err error) {
	authOptions, err := d.resolveRegistryAuthentication(driverConfig, repo)
	if err != nil {
		if driverConfig.AuthSoftFail {
			d.logger.Warn("Failed to find docker repo auth", "repo", repo, "error", err)
		} else {
			return "", "", fmt.Errorf("Failed to find docker auth for repo %q: %v", repo, err)
		}
	}

	if authIsEmpty(authOptions) {
		d.logger.Debug("did not find docker auth for repo", "repo", repo)
	}

	d.eventer.EmitEvent(&drivers.TaskEvent{
		TaskID:    task.ID,
		AllocID:   task.AllocID,
		TaskName:  task.Name,
		Timestamp: time.Now(),
		Message:   "Downloading image",
		Annotations: map[string]string{
			"image": dockerImageRef(repo, tag),
		},
	})

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Add registry credentials via the task driver config auth block (auth.username/password, auth_email) or DOCKER_AUTH_CONFIG.
2. Configure the client's docker config file (~/.docker/config.json) or Nomad's DockerAuthConfig option so the helper can locate credentials.
3. For ECR, enable the ECR credential helper / set GC to refresh credentials.
4. If auth is optional for this image, set auth_soft_fail = true so the driver warns instead of failing.

Example fix

// before
config {
  image = "private.registry/app:1.0"
}
// after
config {
  image = "private.registry/app:1.0"
  auth {
    username = "user"
    password = "pass"
    server_address = "private.registry"
  }
}

// pre-check credentials exist before job submit
if strings.Contains(cfg.Image, "private.registry") && cfg.Auth == nil {
	log.Fatal("private registry image requires docker auth config")
}

// soft-fail alternative
if err != nil {
	if strings.Contains(err.Error(), "Failed to find docker auth") && cfg.AuthSoftFail {
		logger.Warn("continuing without registry auth", "err", err)
	} else {
		return err
	}
}

When it happens

Trigger: Task pulls from a private registry while no docker auth config exists (no DOCKER_AUTH_CONFIG in task config, no DockerConfigHelper/auth helper on the client, no dockerd credential store), and driverConfig.AuthSoftFail is false.

Common situations: Pulling from a private ECR/GCR/Artifactory registry without configured credentials, expired registry credentials, missing docker.config on the Nomad client, or moving an image from Docker Hub to a private registry without updating auth.

Related errors

• Failed to pull `%s`: %w
• Failed to open auth config file: %v, error: %v
• Failed to parse auth config file: %v
• no signed workload identity available
• JWT login returned an empty secret

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