What causes "env string too large (max %d bytes)" in wavetermdev/waveterm?

Reduce the size of the value being set (move large data to a file and store its path in the env var).

env string too large

Error message

env string too large (max %d bytes)

What it means

SetEnv returns this when the resulting serialized environment string (existing env block plus the new key/value pair) would exceed MaxEnvSize (1 MiB). Wave stores the block environment as a single serialized string, so the total size of the whole block env is capped to keep RPC payloads bounded. The write is rejected before mutating the env map.

Solutions

Reduce the size of the value being set (move large data to a file and store its path in the env var).
Remove unused env vars from the block environment (SetEnv with empty values or via the settings UI) before adding the new one.
Store large configuration in wave config files or the app's own storage instead of the block environment.
Split work across multiple blocks with smaller environments.

Example fix

// before
envutil.SetEnv(envStr, "CERT_BUNDLE", string(pemBytes)) // errors if envStr+pemBytes > 1MiB

// after
os.WriteFile("/path/to/bundle.pem", pemBytes, 0600)
envutil.SetEnv(envStr, "CERT_BUNDLE_PATH", "/path/to/bundle.pem")

Defensive patterns

Strategy: validation

Validate before calling

// estimate current block env size before SetEnv
existingLen := len(envStr)
if existingLen + len(key) + len(val) + 2 > 1024*1024 {
    return fmt.Errorf("env var %q would exceed 1MiB block-env limit", key)
}
_, err := envutil.SetEnv(envStr, key, val)

Try / catch

// Go: check the returned error
newEnv, err := envutil.SetEnv(envStr, key, val)
if err != nil && strings.Contains(err.Error(), "env string too large") {
    // trim existing env or move value to a file, then retry
}

Prevention

Keep env var values small; store large payloads in files and pass paths
Audit block environments periodically for stale/large variables
Check len(key)+len(val)+2+len(envStr) against MaxEnvSize before calling
Never embed certificates, blobs, or tokens directly in env vars

When it happens

Trigger: Calling SetEnv when len(key)+len(val)+2+len(existing env string) > 1024*1024. Typically adding a large value (e.g. embedding a token, cert, or JSON blob in an env var) to a block that already has many/large env vars.

Common situations: Embedding secrets or base64 blobs in env vars; accumulating dozens of env vars on a long-lived block; migrating environments that exceed the 1 MiB block-env limit.

Related errors

AI-assisted analysis of wavetermdev/waveterm@a4447c1563 (2026-09-01). Data as JSON: /api/errors/7da7a1f930615c22. Report an issue: GitHub.

Appendix: source

Thrown at pkg/util/envutil/envutil.go:57

		sb.WriteByte('\x00')
	}
	return sb.String()
}

func GetEnv(envStr string, key string) string {
	envMap := EnvToMap(envStr)
	return envMap[key]
}

func SetEnv(envStr string, key string, val string) (string, error) {
	if strings.ContainsAny(key, "=\x00") {
		return "", fmt.Errorf("key cannot contain '=' or '\\x00'")
	}
	if strings.Contains(val, "\x00") {
		return "", fmt.Errorf("value cannot contain '\\x00'")
	}
	if len(key)+len(val)+2+len(envStr) > MaxEnvSize {
		return "", fmt.Errorf("env string too large (max %d bytes)", MaxEnvSize)
	}
	envMap := EnvToMap(envStr)
	envMap[key] = val
	rtnStr := MapToEnv(envMap)
	return rtnStr, nil
}

func RmEnv(envStr string, key string) string {
	envMap := EnvToMap(envStr)
	delete(envMap, key)
	return MapToEnv(envMap)
}

func SliceToEnv(env []string) string {
	var sb strings.Builder
	for _, envVar := range env {
		if len(envVar) == 0 {
			continue

View on GitHub (pinned to a4447c1563)