What causes "failed to write bootstrap environment: %w" in hashicorp/nomad?

Check the wrapped OS error to identify the filesystem cause

failed to write bootstrap environment: %w

Error message

failed to write bootstrap environment: %w

What it means

The hook also writes the envoy bootstrap environment variables as JSON to .envoy_bootstrap.env in the SecretsDir for debugging. os.Create failing for this env file produces 'failed to write bootstrap environment', wrapping the OS error. As with the .cmd file, this affects only the debug artifact path in Prestart.

Source

Thrown at client/allocrunner/taskrunner/envoy_bootstrap_hook.go:333

	bootstrapArgs := bootstrap.args()

	// Write args to file for debugging
	argsFile, err := os.Create(bootstrapCmdPath)
	if err != nil {
		return fmt.Errorf("failed to write bootstrap command line: %w", err)
	}
	defer argsFile.Close()
	if _, err := io.WriteString(argsFile, strings.Join(bootstrapArgs, " ")+"\n"); err != nil {
		return fmt.Errorf("failed to encode bootstrap command line: %w", err)
	}

	// Create environment
	bootstrapEnv := bootstrap.env(h.groupEnv())

	// Write env to file for debugging
	envFile, err := os.Create(bootstrapEnvPath)
	if err != nil {
		return fmt.Errorf("failed to write bootstrap environment: %w", err)
	}
	defer envFile.Close()
	envEnc := json.NewEncoder(envFile)
	envEnc.SetIndent("", "    ")
	if err := envEnc.Encode(bootstrapEnv); err != nil {
		return fmt.Errorf("failed to encode bootstrap environment: %w", err)
	}

	// keep track of latest error returned from exec-ing consul envoy bootstrap
	var cmdErr error

	backoffOpts := decay.BackoffOptions{
		MaxSleepTime:   h.envoyBootstrapWaitTime,
		InitialGapSize: h.envoyBootstrapInitialGap,
		MaxJitterSize:  h.envoyBootstrapMaxJitter,
		Sleeper:        h.envoyBootstrapExpSleep,
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

Check the wrapped OS error to identify the filesystem cause
Verify SecretsDir exists and the Nomad client user can create files in it
Free disk space if ENOSPC
Correct security-module (SELinux/AppArmor) denials if present
Retry the allocation once the filesystem is healthy

Defensive patterns

Strategy: validation

Validate before calling

if info, err := os.Stat(secretsDir); err != nil || !info.IsDir() {
    return fmt.Errorf("env bootstrap target dir %s unavailable: %w", secretsDir, err)
}
if free, err := diskFree(secretsDir); err == nil && free < 1<<20 {
    return errors.New("insufficient disk space for envoy bootstrap debug files")
}

Try / catch

if err := hook.Prestart(req); err != nil {
    var pe *os.PathError
    if errors.As(err, &pe) && strings.Contains(err.Error(), "bootstrap environment") {
        log.Printf("env debug file creation failed on %s: %v", pe.Path, pe.Err)
    }
    return err
}

Prevention

Verify secrets dir existence/permissions before the envoy hook runs
Alert on low disk space for the client data volume
Ensure mounts used by the client (including in containers) are writable
Fix SELinux/AppArmor denials affecting the secrets directory

When it happens

Trigger: os.Create(bootstrapEnvPath) fails due to a missing/read-only SecretsDir, ENOSPC, or permission/SELinux restrictions on file creation in the secrets directory.

Common situations: Client disk full; secrets dir permissions broken after host changes; containerized client where the secrets mount is not writable.

Understand the failure class

Background: "Permission denied" / "Failed to write" file errors: why a library can't write its files to disk (EACCES, EPERM, ENOSPC) and how to fix them — this error's family across 43 libraries.

Related errors

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