hashicorp/nomad · error

failed to parse 'image_pull_timeout' duration: %v

Error message

failed to parse 'image_pull_timeout' duration: %v

What it means

The Docker driver validates the optional 'image_pull_timeout' plugin configuration by passing it to time.ParseDuration. If the string is not a valid Go duration literal (e.g. "5m", "30s"), driver setup fails immediately with this wrapped parse error. It is a plugin-configuration validation error, not a runtime pull failure.

Source

Thrown at drivers/docker/config.go:828

		}
		if dur < pullActivityTimeoutMinimum {
			return fmt.Errorf("pull_activity_timeout is less than minimum, %v", pullActivityTimeoutMinimum)
		}
		d.config.pullActivityTimeoutDuration = dur
	}

	if d.config.InfraImagePullTimeout != "" {
		dur, err := time.ParseDuration(d.config.InfraImagePullTimeout)
		if err != nil {
			return fmt.Errorf("failed to parse 'infra_image_pull_timeout' duration: %v", err)
		}
		d.config.infraImagePullTimeoutDuration = dur
	}

	if d.config.ImagePullTimeout != "" {
		_, err := time.ParseDuration(d.config.ImagePullTimeout)
		if err != nil {
			return fmt.Errorf("failed to parse 'image_pull_timeout' duration: %v", err)
		}
	}

	if err := validateAllowedNamespace(d.config.AllowedModes); err != nil {
		return err
	}
	d.config.allowRuntimes = make(map[string]struct{}, len(d.config.AllowRuntimesList))
	for _, r := range d.config.AllowRuntimesList {
		d.config.allowRuntimes[r] = struct{}{}
	}

	if c.AgentConfig != nil {
		d.clientConfig = c.AgentConfig.Driver
	}

	dockerClient, err := d.getDockerClient()
	if err != nil {
		return fmt.Errorf("failed to get docker client: %v", err)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Fix the duration string to a valid Go duration with a unit, e.g. "5m" or "300s".
2. Check for stray characters, spaces, or quoted-inside-quote issues in the Nomad agent config (HCL) at the image_pull_timeout key.
3. If no timeout override is wanted, remove the image_pull_timeout key entirely rather than setting it to an empty/invalid value.
4. Validate the config with 'nomad agent -config ... -verify-only' before restarting agents.

Example fix

// before (Nomad agent HCL)
plugin "docker" {
  config {
    image_pull_timeout = "300"
  }
}
// after
plugin "docker" {
  config {
    image_pull_timeout = "5m"
  }
}

// Go: validate before applying driver config
if cfg.ImagePullTimeout != "" {
    if _, err := time.ParseDuration(cfg.ImagePullTimeout); err != nil {
        return fmt.Errorf("invalid image_pull_timeout %q: %w", cfg.ImagePullTimeout, err)
    }
}

errcheck: handle the setup error and refuse to start the agent/driver with a clear message naming the offending key.

When it happens

Trigger: Setting 'image_pull_timeout' in the docker driver plugin configuration to a string that time.ParseDuration cannot parse, e.g. missing unit ('30'), misspelled unit ('5mins'), or empty garbage text.

Common situations: Operators write 'image_pull_timeout = "300"' forgetting Go durations require a unit, or copy Linux-style '5m30' without units, or a config management template injects an empty string with different formatting.

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: %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/e5fe95d8e33bfcac. Report an issue: GitHub.