wavetermdev/waveterm · critical

no auth key found in environment variables

Error message

no auth key found in environment variables

What it means

SetAuthKeyFromEnv reads the WAVE_AUTHKEY environment variable and stores it as the server's auth key. If the variable is unset or empty, the server cannot establish an authentication key and returns this error instead of silently running unauthenticated.

Source

Thrown at pkg/authkey/authkey.go:31

const WaveAuthKeyEnv = "WAVETERM_AUTH_KEY"
const AuthKeyHeader = "X-AuthKey"

func ValidateIncomingRequest(r *http.Request) error {
	reqAuthKey := r.Header.Get(AuthKeyHeader)
	if reqAuthKey == "" {
		return fmt.Errorf("no x-authkey header")
	}
	if reqAuthKey != GetAuthKey() {
		return fmt.Errorf("x-authkey header is invalid")
	}
	return nil
}

func SetAuthKeyFromEnv() error {
	authkey = os.Getenv(WaveAuthKeyEnv)
	if authkey == "" {
		return fmt.Errorf("no auth key found in environment variables")
	}
	os.Unsetenv(WaveAuthKeyEnv)
	return nil
}

func GetAuthKey() string {
	return authkey
}

View on GitHub (pinned to a4447c1563)

Solutions

1. Export WAVE_AUTHKEY before launching the server: export WAVE_AUTHKEY=$(openssl rand -hex 32)
2. Check that the service manager / launch script actually forwards the variable (e.g. systemd Environment= or EnvironmentFile=)
3. Fix typos in the variable name in your shell profile or wrapper scripts
4. If keys are generated by a launcher, confirm the launcher ran before the server start

Example fix

// before
wave-server   # WAVE_AUTHKEY unset
// after
export WAVE_AUTHKEY=$(openssl rand -hex 32)
wave-server

if os.Getenv("WAVE_AUTHKEY") == "" {
    return fmt.Errorf("WAVE_AUTHKEY must be set before starting the server")
}

if err := authkey.SetAuthKeyFromEnv(); err != nil {
    log.Fatalf("authkey setup failed: %v", err)
}

When it happens

Trigger: Calling SetAuthKeyFromEnv (via grabAndRemoveEnvVars) when os.Getenv(WaveAuthKeyEnv) returns an empty string — i.e. WAVE_AUTHKEY was never exported into the server process environment.

Common situations: Starting the Wave server from a shell or service manager that does not pass WAVE_AUTHKEY; a .env file not loaded into the process environment; a typo like WAVEAUTHKEY or WAVE_AUTH_KEY in launch scripts or systemd unit files.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• setting auth key: %v
• Invalid CSS color: ${color}
• no WAVETERM_TABID env var set
• no WAVETERM_TABID env var set
• No appropriate secret manager found, cannot set secrets

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