hashicorp/nomad · error

Failed to parse image_pull_timeout: %v

Error message

Failed to parse image_pull_timeout: %v

What it means

pullImage parses the driver's image_pull_timeout config value with time.ParseDuration; this error means the configured string is not a valid Go duration. No pull starts because the pull deadline cannot be computed.

Source

Thrown at drivers/docker/driver.go:682

	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),
		},
	})

	pullDur, err := time.ParseDuration(driverConfig.ImagePullTimeout)
	if err != nil {
		return "", "", fmt.Errorf("Failed to parse image_pull_timeout: %v", err)
	}

	return d.coordinator.PullImage(driverConfig.Image, authOptions, task.ID, d.emitEventFunc(task), pullDur, d.config.pullActivityTimeoutDuration)
}

func (d *Driver) emitEventFunc(task *drivers.TaskConfig) LogEventFn {
	return func(msg string, annotations map[string]string) {
		d.eventer.EmitEvent(&drivers.TaskEvent{
			TaskID:      task.ID,
			AllocID:     task.AllocID,
			TaskName:    task.Name,
			Timestamp:   time.Now(),
			Message:     msg,
			Annotations: annotations,
		})
	}
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Use a valid Go duration string: number plus unit such as "30s", "5m", "1h".
2. Remove any spaces or extra characters from the value.
3. If no custom timeout is needed, delete the field to fall back to the default.
4. Test the string with `go tool` / mentally verify against time.ParseDuration rules.

Example fix

// before
config {
  image_pull_timeout = "600"
}
// after
config {
  image_pull_timeout = "10m"
}

func validDuration(s string) bool {
	_, err := time.ParseDuration(s)
	return err == nil
}
// ensure image_pull_timeout like "10m", "45s"; reject "600"

When it happens

Trigger: image_pull_timeout in the task docker config (or plugin config) is set to a string ParseDuration rejects, e.g. "10m", "600" (missing unit), "ten minutes", or "5m30".

Common situations: Forgetting the time unit ("600" instead of "600s"), using unsupported units like "5min", copy-pasting durations with spaces, or typo during hand-editing of job files.

Understand the failure class

Background: "invalid duration" / "failed to parse duration": why your timeout, interval, or TTL string is rejected and which formats each library accepts — this error's family across 32 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.
• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• failed to parse 'image_pull_timeout' duration: %v
• error parsing rpc_handshake_timeout: %v
• start_timeout should be greater than 0s
• Error parsing max kill timeout: %s
• failed to parse 'image_delay' duration: %v

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