wavetermdev/waveterm · critical

setting auth key: %v

Error message

setting auth key: %v

What it means

The wave server requires an auth key and reads it from the environment via authkey.SetAuthKeyFromEnv during startup. If that fails (missing or invalid expected env vars), grabAndRemoveEnvVars wraps the cause as "setting auth key: %v" and aborts startup.

Source

Thrown at cmd/server/main-server.go:402

func createMainWshClient() {
	rpc := wshserver.GetMainRpcClient()
	wshutil.DefaultRouter.RegisterTrustedLeaf(rpc, wshutil.DefaultRoute)
	wps.Broker.SetClient(wshutil.DefaultRouter)
	localInitialEnv := envutil.PruneInitialEnv(envutil.SliceToMap(os.Environ()))
	sockName := wavebase.GetDomainSocketName()
	remoteImpl := wshremote.MakeRemoteRpcServerImpl(nil, wshutil.DefaultRouter, wshclient.GetBareRpcClient(), true, localInitialEnv, sockName)
	localConnWsh := wshutil.MakeWshRpc(wshrpc.RpcContext{Conn: wshrpc.LocalConnName}, remoteImpl, "conn:local")
	go wshremote.RunSysInfoLoop(localConnWsh, wshrpc.LocalConnName)
	wshutil.DefaultRouter.RegisterTrustedLeaf(localConnWsh, wshutil.MakeConnectionRouteId(wshrpc.LocalConnName))
	wshfs.RpcClient = localConnWsh
	wshfs.RpcClientRouteId = wshutil.MakeConnectionRouteId(wshrpc.LocalConnName)
}

func grabAndRemoveEnvVars() error {
	err := authkey.SetAuthKeyFromEnv()
	if err != nil {
		return fmt.Errorf("setting auth key: %v", err)
	}
	err = wavebase.CacheAndRemoveEnvVars()
	if err != nil {
		return err
	}
	err = wcloud.CacheAndRemoveEnvVars()
	if err != nil {
		return err
	}

	// Remove WAVETERM env vars that leak from prod => dev
	os.Unsetenv("WAVETERM_CLIENTID")
	os.Unsetenv("WAVETERM_WORKSPACEID")
	os.Unsetenv("WAVETERM_TABID")
	os.Unsetenv("WAVETERM_BLOCKID")
	os.Unsetenv("WAVETERM_CONN")
	os.Unsetenv("WAVETERM_JWT")
	os.Unsetenv("WAVETERM_VERSION")

View on GitHub (pinned to a4447c1563)

Solutions

1. Launch the server via the official launcher (wlash/wave) which sets the auth key env vars.
2. Inspect the wrapped inner error for the precise env problem (missing var vs invalid format).
3. Set the expected auth-key env vars manually for the server process.
4. Ensure grabAndRemoveEnvVars runs before any code that consumes the env vars.
5. Verify no wrapper script unsets the relevant environment entries.

Example fix

// before
WAVESERVER_BIN   # run directly, no auth key in env -> startup error
// after
export WAVE_AUTHKEY=<key-from-launcher>
WAVESERVER_BIN   # or start via the wave launcher which sets the key

if os.Getenv("WAVE_AUTHKEY") == "" { // whichever vars authkey expects
    return fmt.Errorf("auth key env var missing; launch via the wave launcher")
}

if err := grabAndRemoveEnvVars(); err != nil {
    log.Fatalf("server startup failed: %v", err) // inspect wrapped cause
}

When it happens

Trigger: Starting cmd/server (waveserver) when the auth-key environment variables are absent, malformed, or fail validation in authkey.SetAuthKeyFromEnv; the underlying error is appended after the colon.

Common situations: Running the server under a service manager that strips env vars; invoking the binary directly without the launcher that normally sets the auth key; stale/partial env after an upgrade.

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

• error getting client: %v
• no auth key found in environment variables
• 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/1f0c3646da691a04. Report an issue: GitHub.