JuliusBrussee/caveman · error

native runtime: unknown event

Error message

native runtime: unknown event %q

What it means

The native runtime's Handle method validates that the incoming request's event type is one of the known event types before processing it. If request.Event.Type is not registered in the eventTypes set, Handle refuses the request with this error. This guards the runtime IPC protocol against malformed or stale clients sending unrecognized events.

Solutions

1. Check the event type string for typos against the eventTypes map keys in proxy/internal/nativeruntime/runtime.go
2. Rebuild/restart both client and runtime so protocol versions and event sets match
3. If the event is legitimately new, register it in eventTypes and add its handling case

Example fix

// before
resp, err := rt.Handle(ctx, Request{Event: Event{Type: "session-close"}})
// after
resp, err := rt.Handle(ctx, Request{Event: Event{Type: "session_end"}})

var knownEvents = map[string]bool{"session_start": true, "session_end": true}
if !knownEvents[req.Event.Type] {
	return fmt.Errorf("unsupported event %q", req.Event.Type)
}

func isKnownEvent(t string) bool { _, ok := eventTypes[t]; return ok }

When it happens

Trigger: Calling Handle with a request whose Event.Type is not a key of eventTypes (e.g. a typo like "sesion_end", an event added in a newer client but unknown to an older runtime, or a client built against a different protocol).

Common situations: Version skew between the coding agent/proxy client and the runtime binary; hand-crafted JSON sent over the unix socket; typos in event names; tests or scripts that invent event names.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• apiKey, baseURL, and agent are required
• arm must be or
• artifact_id is required
• artifactId is required
• ASGI context resolver or request bounds are invalid

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/a9dc47891379ef03. Report an issue: GitHub.

Appendix: source

Thrown at proxy/internal/nativeruntime/runtime.go:215

		return profile, profileFeatures{taskContract: true, compactState: true}, nil
	case "full-safe", "full-max":
		return profile, profileFeatures{taskContract: true, compactState: true, reuse: true, capture: true, mask: true, repository: true}, nil
	default:
		return "", profileFeatures{}, fmt.Errorf("native runtime: unknown profile %q", raw)
	}
}

func (r *Runtime) Handle(_ context.Context, request Request) (Response, error) {
	started := time.Now()
	sessionLock := r.sessionLock(request.Session.ID)
	sessionLock.Lock()
	defer sessionLock.Unlock()

	if request.ProtocolVersion != ProtocolVersion {
		return Response{}, fmt.Errorf("native runtime: unsupported protocol version %d", request.ProtocolVersion)
	}
	if _, ok := eventTypes[request.Event.Type]; !ok {
		return Response{}, fmt.Errorf("native runtime: unknown event %q", request.Event.Type)
	}
	if strings.TrimSpace(request.Session.ID) == "" {
		return Response{}, errors.New("native runtime: session id is required")
	}
	policyMode := request.PolicyMode
	if policyMode == "" {
		policyMode = "safe"
	}
	if policyMode != "record" && policyMode != "safe" && policyMode != "max" {
		return Response{}, fmt.Errorf("native runtime: unknown policy mode %q", policyMode)
	}
	request.PolicyMode = policyMode
	profile, features, err := resolveProfile(request.Profile, policyMode)
	if err != nil {
		return Response{}, err
	}
	request.Profile = profile
	r.mu.Lock()

View on GitHub (pinned to 3ee70a1026)