hashicorp/nomad · error

failed to download artifact %q: %v

Error message

failed to download artifact %q: %v

What it means

In the artifact hook's download worker, h.getter.Get failed to fetch an artifact (network error, bad URL, auth failure); it is wrapped as a recoverable error so the task runner can apply restart/backoff policy rather than immediately failing the task.

Source

Thrown at client/allocrunner/taskrunner/artifact_hook.go:58

	wg *sync.WaitGroup,
	responseStateMutex *sync.Mutex,
) {
	defer wg.Done()
	for artifact := range jobs {
		aid := artifact.Hash()
		if req.PreviousState[aid] != "" {
			h.logger.Trace("skipping already downloaded artifact", "artifact", artifact.GetterSource)
			responseStateMutex.Lock()
			resp.State[aid] = req.PreviousState[aid]
			responseStateMutex.Unlock()
			continue
		}

		h.logger.Debug("downloading artifact", "artifact", artifact.GetterSource, "aid", aid)

		if err := h.getter.Get(req.TaskEnv, artifact, req.Task.User); err != nil {
			wrapped := structs.NewRecoverableError(
				fmt.Errorf("failed to download artifact %q: %v", artifact.GetterSource, err),
				true,
			)
			herr := te.NewHookError(wrapped, structs.NewTaskEvent(structs.TaskArtifactDownloadFailed).SetDownloadError(wrapped))

			errorChannel <- herr
			continue
		}

		// Mark artifact as downloaded to avoid re-downloading due to
		// retries caused by subsequent artifacts failing. Any
		// non-empty value works.
		responseStateMutex.Lock()
		resp.State[aid] = "1"
		responseStateMutex.Unlock()
	}
}

func (*artifactHook) Name() string {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the wrapped getter error for the root cause (DNS, 404, TLS, auth)
2. Verify the artifact source URL is reachable from the client
3. Check artifact options (headers, checksum) in the job spec
4. Let Nomad retry; fix the artifact host if it is down

When it happens

Trigger: Thrown at client/allocrunner/taskrunner/artifact_hook.go:58 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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