joewalnes/websocketd · error

--maxframesize must not be negative; use 0 for unlimited

Error message

--maxframesize must not be negative; use 0 for unlimited

What it means

validateMaxFrameSize rejects negative --maxframesize values. The WebSocket read limit is only applied for positive values, so a negative value silently meant 'unlimited' — quietly removing the DoS protection the flag exists for (issue #472).

Source

Thrown at config.go:174

}

// validateAnyOrigin checks that --anyorigin is not combined with an actual
// origin policy. The flags say opposite things, and silently preferring one
// would hide operator confusion.
func validateAnyOrigin(anyOrigin, sameOrigin bool, allowOrigins []string) error {
	if anyOrigin && (sameOrigin || allowOrigins != nil) {
		return fmt.Errorf("--anyorigin means 'accept any origin' and cannot be combined with --sameorigin or --origin, which restrict it")
	}
	return nil
}

// validateMaxFrameSize rejects negative --maxframesize values. The read
// limit is only applied for positive values, so a negative value silently
// meant "unlimited" — the one value an operator can pass that quietly
// removes the DoS protection the flag exists for (issue #472).
func validateMaxFrameSize(maxFrameSize int64) error {
	if maxFrameSize < 0 {
		return fmt.Errorf("--maxframesize must not be negative; use 0 for unlimited")
	}
	return nil
}

// buildParentEnv constructs the filtered parent environment variable list.
func buildParentEnv(passenv string) []string {
	env := make([]string, 0)
	newlineCleaner := strings.NewReplacer("\n", " ", "\r", " ")
	for _, key := range strings.Split(passenv, ",") {
		if key == "HTTPS" {
			continue
		}
		if v := os.Getenv(key); v != "" {
			if clean := strings.TrimSpace(newlineCleaner.Replace(v)); clean != "" {
				env = append(env, fmt.Sprintf("%s=%s", key, clean))
			}
		}
	}

View on GitHub (pinned to 7a8683dc7f)

Solutions

1. Use --maxframesize=0 for unlimited frames
2. Pass a positive byte value, e.g. --maxframesize=1048576 for 1 MiB
3. Fix scripts/templates that default the flag to -1

Example fix

// before
websocketd --maxframesize=-1 --port=8080 ./script.sh
// after
websocketd --maxframesize=0 --port=8080 ./script.sh

if (maxFrameSize < 0) throw new Error('--maxframesize must not be negative; use 0 for unlimited');

const validFrameSize = (n) => Number.isInteger(n) && n >= 0;

try { startServer(args) } catch (e) { if (/maxframesize must not be negative/.test(e)) console.error('use 0 for unlimited, not -1'); throw e; }

When it happens

Trigger: Running websocketd with --maxframesize=-1 (or any negative number). Previously this silently disabled the frame-size limit; now startup fails.

Common situations: Using -1 to mean 'unlimited' by convention from other tools; scripted defaults that substitute -1 when no size is configured.

Understand the failure class

Background: "unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools — this error's family across 24 libraries.

Related errors

• --socketmode %q is not an octal permission mode (e.g. 0700)
• --socketmode %q has bits beyond permission bits (keep it wit
• --socketmode 0 would make the socket unusable; pick a mode l
• please specify both --sslcert and --sslkey when requesting -
• you should not be using --ssl* flags when there is no --ssl

AI-assisted analysis of joewalnes/websocketd@7a8683dc7f (2026-09-03). Data as JSON: /api/errors/7492feb36df3ee56. Report an issue: GitHub.