hashicorp/nomad · error

hg_timeout must be set

Error message

hg_timeout must be set

What it means

Artifact config validation found hg_timeout unset (nil) in the artifact stanza; the field is mandatory when the artifact configuration is validated.

Source

Thrown at nomad/structs/config/artifact.go:203

		return fmt.Errorf("gcs_timeout must be set")
	}
	if v, err := time.ParseDuration(*a.GCSTimeout); err != nil {
		return fmt.Errorf("gcs_timeout not a valid duration: %w", err)
	} else if v < 0 {
		return fmt.Errorf("gcs_timeout must be > 0")
	}

	if a.GitTimeout == nil {
		return fmt.Errorf("git_timeout must be set")
	}
	if v, err := time.ParseDuration(*a.GitTimeout); err != nil {
		return fmt.Errorf("git_timeout not a valid duration: %w", err)
	} else if v < 0 {
		return fmt.Errorf("git_timeout must be > 0")
	}

	if a.HgTimeout == nil {
		return fmt.Errorf("hg_timeout must be set")
	}
	if v, err := time.ParseDuration(*a.HgTimeout); err != nil {
		return fmt.Errorf("hg_timeout not a valid duration: %w", err)
	} else if v < 0 {
		return fmt.Errorf("hg_timeout must be > 0")
	}

	if a.S3Timeout == nil {
		return fmt.Errorf("s3_timeout must be set")
	}
	if v, err := time.ParseDuration(*a.S3Timeout); err != nil {
		return fmt.Errorf("s3_timeout not a valid duration: %w", err)
	} else if v < 0 {
		return fmt.Errorf("s3_timeout must be > 0")
	}

	if a.DecompressionFileCountLimit == nil {
		return fmt.Errorf("decompression_file_count_limit must not be nil")

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set hg_timeout to a valid duration such as "10s" in the client's artifact config

Example fix

// before
artifact {
  git_timeout = "5m"
}
// after
artifact {
  git_timeout = "5m"
  hg_timeout  = "5m"
}

func hasHgTimeout(c *ArtifactConfig) bool { return c != nil && c.HgTimeout != nil }

func hgTimeoutSet(a ArtifactConfig) bool { return a.HgTimeout != nil }

When it happens

Trigger: Omitting `hg_timeout` from an artifact config block; constructing an ArtifactConfig struct in Go with HgTimeout nil; using config files written before hg_timeout existed.

Common situations: Configs that only set git/http timeouts while including hg sources; legacy agent config carried forward across upgrades; programmatic config builders leaving optional pointer fields unset.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• wait config is nil or empty
• missing datacenter for client registration
• default_identity_ttl must be greater than 0
• max_identity_ttl must be greater than 0
• max_identity_ttl must be greater than or equal to default_id

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