hashicorp/nomad · error

http_read_timeout must be set

Error message

http_read_timeout must be set

What it means

ArtifactConfig.Validate requires the http_read_timeout option to be present; it is stored as a *string so a missing key is distinguishable from an empty one. If HTTPReadTimeout is nil the artifact download configuration is incomplete and validation fails immediately with this error. Nomad needs this timeout to bound artifact fetch HTTP reads.

Source

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

	case !pointer.Eq(a.DisableArtifactInspection, o.DisableArtifactInspection):
		return false
	case !pointer.Eq(a.DisableFilesystemIsolation, o.DisableFilesystemIsolation):
		return false
	case !helper.SliceSetEq(a.FilesystemIsolationExtraPaths, o.FilesystemIsolationExtraPaths):
		return false
	case !pointer.Eq(a.SetEnvironmentVariables, o.SetEnvironmentVariables):
		return false
	}
	return true
}

func (a *ArtifactConfig) Validate() error {
	if a == nil {
		return fmt.Errorf("artifact must not be nil")
	}

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

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Add http_read_timeout to the client artifact config block, e.g. artifact { http_read_timeout = "30s" }.
2. If building config programmatically, set Artifact.HTTPReadTimeout to a duration string before Validate.
3. Start from Nomad's default agent config template which includes artifact defaults.
4. Check for provisioning tooling stripping the key from the generated config.

Example fix

// before (HCL)
client {
  artifact {}
}
// after
client {
  artifact {
    http_read_timeout = "30s"
  }
}

if cfg.Artifact.HTTPReadTimeout == nil {
    cfg.Artifact.HTTPReadTimeout = ptr.Of("30s")
}

if err := cfg.Artifact.Validate(); err != nil {
    if strings.Contains(err.Error(), "http_read_timeout must be set") {
        // add the missing artifact option to the client config
    }
    return err
}

When it happens

Trigger: Running nomad agent (client mode) with an artifact { http_read_timeout = ... } block omitted from the client config, causing the pointer to remain nil during Validate.

Common situations: Minimal agent configs written before the option existed; config files copied from old setups after upgrading Nomad that introduced artifact HTTP tuning options; provisioning tools that strip unknown keys.

Understand the failure class

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

Related errors

• http_max_size must be set
• wait config is nil or empty
• missing node ID for client registration
• missing datacenter for client registration
• missing node name for client registration

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