What causes "invalid context, router cannot have a proc-route" in wavetermdev/waveterm?

Clear ProcRoute for router contexts (IsRouter implies no proc-route)

invalid context, router cannot have a proc-route

Error message

invalid context, router cannot have a proc-route

What it means

Creation-time validation: a router context must not have a proc-route (process route) attached. Returned when the router context is constructed or validated while a proc-route is present, since proc-routes belong to endpoint contexts, not routers.

Source

Thrown at pkg/wshutil/wshrouter_controlimpl.go:300

	}

	routeId := MakeJobRouteId(data.JobId)
	log.Printf("wshrouter authenticate-jobmanager success linkid=%d jobid=%q routeid=%q", linkId, data.JobId, routeId)
	impl.Router.trustLink(linkId, LinkKind_Leaf)
	impl.Router.bindRoute(linkId, routeId, true)

	return nil
}

func validateRpcContextFromAuth(newCtx *wshrpc.RpcContext) (string, error) {
	if newCtx == nil {
		return "", fmt.Errorf("no context found in jwt token")
	}
	if newCtx.IsRouter && newCtx.RouteId != "" {
		return "", fmt.Errorf("invalid context, router cannot have a routeid")
	}
	if newCtx.IsRouter && newCtx.ProcRoute {
		return "", fmt.Errorf("invalid context, router cannot have a proc-route")
	}
	if !newCtx.IsRouter && newCtx.RouteId == "" && !newCtx.ProcRoute {
		return "", fmt.Errorf("invalid context, must have a routeid")
	}
	if newCtx.IsRouter {
		return "", nil
	}
	return newCtx.GenerateRouteId(), nil
}

View on GitHub (pinned to a4447c1563)

Solutions

Clear ProcRoute for router contexts (IsRouter implies no proc-route)
Fix token generation so router tokens set only IsRouter
Ensure proc-route clients are not marked IsRouter

Example fix

// before
ctx := wshrpc.RpcContext{IsRouter: true, ProcRoute: true}
// after
ctx := wshrpc.RpcContext{IsRouter: true, ProcRoute: false}

Defensive patterns

Strategy: validation

Validate before calling

if newCtx.IsRouter && newCtx.ProcRoute {
    return fmt.Errorf("router token context must not set ProcRoute")
}

Type guard

func validRouterContext(c *wshrpc.RpcContext) bool {
    return c.IsRouter && c.RouteId == "" && !c.ProcRoute
}

Try / catch

if _, err := validateRpcContextFromAuth(newCtx); err != nil {
    // re-mint token with ProcRoute cleared for router contexts
}

Prevention

Keep ProcRoute exclusively for leaf proc-route clients
Validate RpcContext flags at token creation time
Add table tests covering valid flag combinations

When it happens

Trigger: Authenticating with a token whose RpcContext has IsRouter:true and ProcRoute:true.

Common situations: Building the auth context by merging flags from multiple sources; proc-route clients incorrectly marked as routers.

Related errors

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