hashicorp/nomad · error

set_environment_variables must be set

Error message

set_environment_variables must be set

What it means

ArtifactConfig.Validate requires SetEnvironmentVariables to be explicitly configured (non-nil *map/*[]string) so artifact drivers unambiguously know whether env vars may be set. A nil value means the config never stated intent, so validation rejects it.

Source

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

		return fmt.Errorf("decompression_size_limit must be < %d but found %d", int64(math.MaxInt64), v)
	}

	if a.DisableArtifactInspection == nil {
		return fmt.Errorf("disable_artifact_inspection must be set")
	}

	if a.DisableFilesystemIsolation == nil {
		return fmt.Errorf("disable_filesystem_isolation must be set")
	}

	for _, p := range a.FilesystemIsolationExtraPaths {
		if _, err := landlock.ParsePath(p); err != nil {
			return fmt.Errorf("filesystem_isolation_extra_paths contains invalid lockdown path %q", p)
		}
	}

	if a.SetEnvironmentVariables == nil {
		return fmt.Errorf("set_environment_variables must be set")
	}

	return nil
}

func DefaultArtifactConfig() *ArtifactConfig {
	return &ArtifactConfig{
		// Read timeout for HTTP operations. Must be long enough to
		// accommodate large/slow downloads.
		HTTPReadTimeout: new("30m"),

		// Maximum download size. Must be large enough to accommodate
		// large downloads.
		HTTPMaxSize: new("100GB"),

		// Timeout for GCS operations. Must be long enough to
		// accommodate large/slow downloads.
		GCSTimeout: new("30m"),

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Add set_environment_variables with an explicit (possibly empty) value to the artifact block
2. Initialize the field programmatically before Validate (e.g. an empty map/list)
3. Base the config on DefaultArtifactConfig()

Example fix

// before
artifact {
  disable_filesystem_isolation = false
}
// after
artifact {
  disable_filesystem_isolation = false
  set_environment_variables = []
}

if cfg.Artifact != nil && cfg.Artifact.SetEnvironmentVariables == nil {
    return errors.New("artifact block must set set_environment_variables explicitly")
}

When it happens

Trigger: Validate() on an ArtifactConfig whose source config omitted set_environment_variables entirely.

Common situations: Minimal artifact blocks written before this field existed; agent configs upgraded from older Nomad versions; programmatic ArtifactConfig{} literals missing the field.

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.

Related errors

• rcp.accept_backlog interval must be greater than zero
• rcp.keep_alive_interval must be greater than zero
• rcp.connection_write_timeout must be greater than zero
• rcp.stream_close_timeout must be greater than zero
• rcp.stream_open_timeout must be greater than zero

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