What causes "failed to stat intro token file: %w" in hashicorp/nomad?

Verify the path in intro_token_file exists: ls -l .

failed to stat intro token file: %w

Error message

failed to stat intro token file: %w

What it means

readIntroTokenFile opens the configured introduction-token file and calls Stat() on it. If Stat fails (typically because the file does not exist, or permissions deny the stat), the underlying error is wrapped as 'failed to stat intro token file'. The caller propagates this instead of loading an intro token.

Source

Thrown at command/agent/agent.go:872

	}

	return nil
}

// readIntroTokenFile attempts to read the intro token from the file system.
func (a *Agent) readIntroTokenFile(cfg *clientconfig.Config) error {

	rootFile, err := os.OpenInRoot(cfg.StateDir, "intro_token.jwt")
	if err != nil {
		if os.IsNotExist(err) {
			return nil
		}
		return err
	}

	fileStat, err := rootFile.Stat()
	if err != nil {
		return fmt.Errorf("failed to stat intro token file: %w", err)
	}

	// If the file exists and is a file, attempt to read the contents and set
	// the intro token. Any error is logged for the operator to investigate but
	// does not block the agent from starting.
	if fileStat.IsDir() {
		return fmt.Errorf("intro token file is a directory")
	}

	content, err := helper.ReadFileContent(rootFile)
	if err != nil {
		return fmt.Errorf("failed to read intro token file: %w", err)
	}

	cfg.IntroToken = strings.TrimSpace(string(content))
	return nil
}

View on GitHub (pinned to 482b49bf1a)

Solutions

Verify the path in intro_token_file exists: ls -l <path>.
Fix file permissions/ownership so the Nomad agent user can stat and read it (chown nomad:nomad; chmod 600).
Ensure the token file is provisioned before the agent starts (init container/systemd ordering, volume mounts).

Example fix

// before (hcl)
client { intro_token_file = "/etc/nomad/tokens/intro" } // file absent
// after (shell)
install -o nomad -g nomad -m 600 /dev/null /etc/nomad/tokens/intro && echo "$TOKEN" > /etc/nomad/tokens/intro
// client { intro_token_file = "/etc/nomad/tokens/intro" }

Defensive patterns

Strategy: validation

Validate before calling

path := cfg.Client.IntroTokenFile
if _, err := os.Stat(path); err != nil {
  return fmt.Errorf("intro token file %q not statable before agent start: %w", path, err)
}

Try / catch

if err := readIntroTokenFile(cfg, path); err != nil {
  var pe *fs.PathError
  if errors.As(err, &pe) {
    log.Errorf("intro token file %s unavailable: %v", path, pe)
  }
  return err
}

Prevention

Provision the token file (with correct ownership) before the agent starts.
Use systemd/init ordering or entrypoint scripts to guarantee file presence.
Mount secrets as files, not directories, and reference the file path.

When it happens

Trigger: client.intro_token_file (the path opened as rootFile) pointing to a nonexistent path, a path in a directory the agent user cannot traverse, or a broken symlink, when finalizeClientConfig calls readIntroTokenFile during startup/reload.

Common situations: Typos in the token file path; file created by root with 0600 while Nomad runs as the nomad user; secret-management provisioning that deleted the file before agent start; containers missing a mounted secret volume.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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