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

Check host disk space and alloc-dir filesystem health; retry the allocation.

failed to encode bootstrap environment: %w

Error message

failed to encode bootstrap environment: %w

What it means

In Nomad's envoy_bootstrap_hook Prestart, after writing secrets/envoy_bootstrap.json (the env file for the consul envoy bootstrap command), a json.Encoder writes the bootstrapEnv map to the file. This error wraps any failure of that Encode call, meaning the environment data could not be serialized to the env file on disk.

Source

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

	}
	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,
	}

	err = h.servicePreflightCheck(ctx, backoffOpts, proxyID)
	if err != nil {
		return err
	}

	// Since Consul services are registered asynchronously with this task

View on GitHub (pinned to 482b49bf1a)

Solutions

Check host disk space and alloc-dir filesystem health; retry the allocation.
Inspect the env file's permissions and that the secrets directory is writable by the Nomad client.
Retry the task; the Prestart hook failure is surfaced in the task events with this message.
If it reproduces on every run, check the Nomad version for bugs and verify no custom hooks mutate bootstrapEnv.

Defensive patterns

Strategy: retry

Validate before calling

// ensure the env file is writable and bootstrapEnv is JSON-safe before Prestart
f, err := os.OpenFile(envFilePath, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0o640)
if err != nil { return err }
if _, err := f.Stat(); err != nil { return err }
if _, err := json.Marshal(bootstrapEnv); err != nil { return fmt.Errorf("bootstrapEnv not JSON-serializable: %w", err) }
f.Close()

Try / catch

err := hook.Prestart(ctx, req)
if err != nil {
    var recoverable *structs.RecoverableError
    if errors.As(err, &recoverable) && recoverable.IsRecoverable() {
        // reschedule/restart the task
    } else {
        // fail the allocation permanently and inspect disk/filesystem
    }
}

Prevention

Monitor alloc-dir disk usage and inode availability.
Keep the secrets directory owned/writable by the Nomad client user.
Avoid injecting non-serializable values into hook environment maps.
Enable Nomad client debug logs when filesystem I/O errors cluster on one host.

When it happens

Trigger: envEnc.Encode(bootstrapEnv) returns a non-nil error during Prestart after the env file was created. In practice Encode on an open writable file rarely fails, but it can if the underlying write fails (disk full, I/O error, file closed/permission revoked mid-write) or if bootstrapEnv contains an unsupported type (e.g. a channel, func, or cyclic value would make Encode fail before writing).

Common situations: Disk-full or I/O problems on the host where the allocation's secrets dir lives; a code change introducing a non-JSON-serializable value into bootstrapEnv; unusual filesystem errors (NFS/EFS hiccups, quota exceeded) in the alloc dir.

Related errors

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