wavetermdev/waveterm · error

env string too large (max %d bytes)

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.

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)

Solutions

1. Reduce the size of the value being set (move large data to a file and store its path in the env var).
2. Remove unused env vars from the block environment (SetEnv with empty values or via the settings UI) before adding the new one.
3. Store large configuration in wave config files or the app's own storage instead of the block environment.
4. 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")

// 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)

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

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

• setting auth key: %v
• input exceeds maximum file size of %d bytes
• electron executable path not set
• failed to build secret environment (ERR-SECRET): %w
• error expanding home dir: %w

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