hashicorp/nomad · error · errEnvProbeQueryFailed

%w: %w

Error message

%w: %w

What it means

wrapProbeError wraps any error from the initial environment probe with errEnvProbeQueryFailed using Go's multi-%w wrapping. It lets callers detect a probe failure via errors.Is(err, errEnvProbeQueryFailed) while still inspecting the underlying cause. It is thrown by the fingerprint retry wrapper when the initial fingerprint probe (e.g. checking if an environment fingerprinter applies) fails.

Source

Thrown at client/fingerprint/fingerprint_retry.go:122

	}

	if shouldSkipEnvFingerprinter(cfg, err) {
		rw.logger.Debug("error performing initial probe, skipping")
		return nil
	}

	rw.logger.Error("fingerprinting failed after all attempts", "error", err)
	return err
}

// errEnvProbeQueryFailed is used to indicate that the initial probe to
// determine if the environment fingerprinter is applicable has failed.
var errEnvProbeQueryFailed = errors.New("fingerprint initial probe failed")

// wrapProbeError wraps the passed error with errEnvProbeQueryFailed to indicate
// that the initial probe has failed.
func wrapProbeError(err error) error {
	return fmt.Errorf("%w: %w", errEnvProbeQueryFailed, err)
}

// shouldSkipEnvFingerprinter determines if an environment fingerprinter should
// be skipped based on the passed configuration and error from the
// fingerprinter. Skipped indicates the client is not running in the environment
// the fingerprinter is designed for.
func shouldSkipEnvFingerprinter(cfg *config.Fingerprint, err error) bool {

	if err == nil {
		return false
	}

	if cfg != nil && cfg.ExitOnFailure != nil {
		return !*cfg.ExitOnFailure
	}

	return errors.Is(err, errEnvProbeQueryFailed)
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Inspect the wrapped cause with errors.Is/As to find the underlying probe failure and fix that (network, missing command, permissions).
2. If the environment genuinely does not match the fingerprinter, configure it to be skipped so the probe is not run.
3. Check the error is transient and rely on the retry wrapper to re-attempt the probe.
4. Update client fingerprint configuration (fingerprint whitelist/blacklist) to disable the problematic fingerprinter.

Example fix

// before
err := fp.Fingerprint(req)
log.Fatal(err)
// after
if err := fp.Fingerprint(req); err != nil {
  if errors.Is(err, errEnvProbeQueryFailed) {
    log.Printf("env probe failed, skipping fingerprinter: %v", err)
    return
  }
  log.Fatal(err)
}

func IsEnvProbeFailed(err error) bool {
	return errors.Is(err, errEnvProbeQueryFailed)
}

if err := fp.Fingerprint(req); err != nil {
	if errors.Is(err, errEnvProbeQueryFailed) {
		log.Printf("env probe failed, skipping: %v", err)
	} else {
		return err
	}
}

When it happens

Trigger: Calling Fingerprint on a fingerprinter wrapped with the retry wrapper when the initial environment probe query returns an error (e.g. an external command or API the environment fingerprinter depends on fails).

Common situations: Running Nomad on a host where an environment-specific probe (cloud metadata, hypervisor detection) fails; network or command errors during client startup fingerprinting; unit tests exercising the retry wrapper with failing probe errors.

Related errors

• lock release: %w
• error executing protected function %w
• failed to fingerprint internal plugins: %v
• failed to fingerprint plugins: %v
• PluginInfo info failed for internal plugin %s: %v

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