hashicorp/nomad · error

git_timeout must be set

Error message

git_timeout must be set

What it means

Returned by ArtifactConfig.Validate when the git_timeout field is nil/absent. Nomad requires git_timeout to be explicitly set so artifact downloads via git cannot hang indefinitely during clone/fetch operations.

Source

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

		return fmt.Errorf("http_max_size must be set")
	}
	if v, err := humanize.ParseBytes(*a.HTTPMaxSize); err != nil {
		return fmt.Errorf("http_max_size not a valid size: %w", err)
	} else if v > math.MaxInt64 {
		return fmt.Errorf("http_max_size must be < %d but found %d", int64(math.MaxInt64), v)
	}

	if a.GCSTimeout == nil {
		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")

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Add an explicit git_timeout to the artifact block, e.g. `git_timeout = "5m"` (large repos may need more).
2. If building the struct in Go, initialize GitTimeout with a valid duration pointer before Validate.
3. Run `nomad validate` to surface any other missing required fields at once.

Example fix

// before
artifact {
  http_max_size = "1gb"
}
// after
artifact {
  http_max_size = "1gb"
  git_timeout   = "5m"
}

func hasGitTimeout(c *ArtifactConfig) bool { return c != nil && c.GitTimeout != nil }

func gitTimeoutSet(a ArtifactConfig) bool { return a.GitTimeout != nil }

When it happens

Trigger: Omitting `git_timeout` from an artifact config block; building an ArtifactConfig struct in Go with GitTimeout left nil; loading a partial/legacy config file that predates the git_timeout field.

Common situations: Writing minimal agent configs with only the artifact source set; copying pre-1.x artifact examples; programmatic config generation skipping 'optional' pointer fields.

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