hashicorp/nomad · error

gcs_timeout must be set

Error message

gcs_timeout must be set

What it means

Returned by ArtifactConfig.Validate when the gcs_timeout field is nil/absent. Nomad requires this timeout to be explicitly configured for artifact downloads from Google Cloud Storage so that a fetch cannot hang forever; a missing value means the artifact block is incomplete.

Source

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

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

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

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Add an explicit gcs_timeout to the artifact block, e.g. `gcs_timeout = "5m"`.
2. If building the struct in Go, set GCSTimeout to a pointer to a valid duration before calling Validate.
3. Re-run `nomad validate` on the config file to catch remaining missing fields.

Example fix

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

func hasGCSTimeout(c *ArtifactConfig) bool { return c != nil && c.GCSTimeout != nil }

func gcsTimeoutSet(a ArtifactConfig) bool { return a.GCSTimeout != nil }

When it happens

Trigger: Omitting `gcs_timeout` entirely from an artifact config block while other fields (like http_max_size) are set; constructing an ArtifactConfig struct in Go with GCSTimeout left as a nil *time.Duration and calling Validate; decoding partial config from an HCL/JSON file missing the key.

Common situations: Hand-writing an agent config and only setting the timeouts you thought mattered; copying an artifact example predating the gcs_timeout field; programmatically building config where optional pointer fields default to nil.

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