feat(frontend): add additional debug information when actor inspector fails to load

[jog1t]

Closes RVT-6021

This pull request enhances error handling and version checking for the Actor Inspector in both the frontend and RivetKit backend. The main improvements include more detailed Inspector error messages, better detection of outdated RivetKit versions (including pre-release versions), and propagation of environment type (local vs deployed) through metadata.

Frontend improvements to Inspector error handling and version checks:

• Added a robust semantic version comparison function isVersionOutdated to accurately detect outdated RivetKit versions, including pre-release tags (e.g., "rc", "alpha") (frontend/src/components/actors/guard-connectable-inspector.tsx).
• Refactored Inspector error handling to provide more specific and actionable messages based on error code, RivetKit version, and environment type. This includes guidance for missing tokens, outdated versions, and unexpected errors, with Sentry reporting for non-standard errors in deployed environments (frontend/src/components/actors/guard-connectable-inspector.tsx) [1] [2].
• Updated the actor metadata fetch logic to include the new type field ("local" or "deployed") in addition to the version, enabling environment-specific error handling (frontend/src/components/actors/actor-inspector-context.tsx).
• Integrated Sentry for error reporting on unexpected Inspector token retrieval errors in deployed environments (frontend/src/components/actors/guard-connectable-inspector.tsx).

Backend (RivetKit) metadata enhancements:

• The MetadataResponse type now includes a type field to indicate whether the environment is "local" or "deployed", and the router endpoint sets this field accordingly (rivetkit-typescript/packages/rivetkit/src/actor/router.ts) [1] [2].

[jog1t]

This change is part of the following stack:

• fix: new project flow incorrect redirect #4341
  • fix: docs-button #4342
    • fix: runner configs being outdated when editing again #4343
      • fix: modals being stuck opaque on firefox #4344
        • feat(frontend): add additional debug information when actor inspector fails to load #4346 ◀
          • feat: add deployments route #4357

_{Change managed by git-spice.}

[railway-app]

🚅 Deployed to the rivet-pr-4346 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
website	😴 Sleeping (View Logs)	Web	Mar 13, 2026 at 3:02 pm
frontend-cloud	😴 Sleeping (View Logs)	Web	Mar 11, 2026 at 10:15 pm
frontend-inspector	😴 Sleeping (View Logs)	Web	Mar 11, 2026 at 10:12 pm
ladle	❌ Build Failed (View Logs)	Web	Mar 11, 2026 at 1:42 pm
mcp-hub	✅ Success (View Logs)	Web	Mar 4, 2026 at 12:02 am

[linear]

RVT-6021 Add debug info for inspector token retrieval failures

[claude]

PR Review

This PR improves Actor Inspector error handling and debug UX. The core feature changes are solid; a few issues worth addressing before merge.

Bugs

Sentry events fire on every render (guard-connectable-inspector.tsx)

buildInspectorTokenErrorMessage calls Sentry.captureException inline, so it fires on every render cycle while the error state persists. This will flood Sentry with duplicate events. Move the Sentry call into a useEffect in ActorContextProvider so it only fires once per unique error.

isVersionOutdated pre-release comparison is incomplete

When both versions have pre-release tags the function returns false (equal). isVersionOutdated("2.0.35-rc.1", "2.0.35-rc.2") returns false, but rc.1 is older. Not critical since RIVET_KIT_MIN_VERSION is a stable release, but could silently break if the min version is ever set to a pre-release.

Missing backend change

The PR description says router.ts was updated to include the type field but that file is absent from the diff. The frontend Zod schema correctly marks type as .optional() so it degrades gracefully, but until the backend sends the field, deployed-environment-specific error messages will never be shown.

Minor issues

createApiTokenQueryOptions uses staleTime: Infinity (cloud-data-provider.tsx)

Once fetched, the token query will never be refetched. If tokens can expire or be rotated, callers will silently use a stale value. If create-once semantics are intentional, a comment would help future maintainers.

isVersionOutdated is untested

The function has version-comparison edge cases and would benefit from unit tests, especially since it gates the "upgrade RivetKit" message shown to users.

as any cast on icon (deploy.ts)

icon: faRivet as any suppresses a type error. Prefer fixing the underlying type mismatch.

Scope

This PR mixes the Inspector error improvements with substantial unrelated additions: managed pools query options, image repositories, Docker tags, API token creation, the new Rivet Cloud deployment option, and UI component updates. Bundling these makes the PR harder to review and revert in isolation.

[pkg-pr-new]

More templates

• actor-actions
• actor-actions-vercel
• ai-agent
• ai-agent-vercel
• example-ai-and-user-generated-actors-freestyle
• chat-room
• chat-room-vercel
• example-cloudflare-workers
• example-cloudflare-workers-hono
• collaborative-document
• collaborative-document-vercel
• cross-actor-actions
• cross-actor-actions-vercel
• example-cursors
• example-cursors-raw-websocket
• example-cursors-raw-websocket-vercel
• example-cursors-vercel
• custom-serverless
• example-elysia
• example-experimental-durable-streams-ai-agent
• example-experimental-durable-streams-ai-agent-vercel
• geo-distributed-database
• geo-distributed-database-vercel
• hello-world
• hello-world-vercel
• example-hono
• hono-react
• hono-react-vercel
• example-kitchen-sink
• example-kitchen-sink-vercel
• multi-region-vercel
• multiplayer-game
• example-multiplayer-game-patterns
• example-multiplayer-game-patterns-vercel
• multiplayer-game-vercel
• native-websockets
• native-websockets-vercel
• next-js
• per-tenant-database
• per-tenant-database-vercel
• example-raw-fetch-handler
• example-raw-fetch-handler-vercel
• example-raw-websocket-handler
• example-raw-websocket-handler-proxy
• example-raw-websocket-handler-proxy-vercel
• example-raw-websocket-handler-vercel
• example-react
• example-react-vercel
• sandbox
• sandbox-coding-agent
• sandbox-coding-agent-vercel
• sandbox-vercel
• scheduling
• scheduling-vercel
• example-sqlite-drizzle
• example-sqlite-raw
• state
• state-vercel
• example-stream
• example-stream-vercel
• example-trpc

@rivetkit/cloudflare-workers

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/cloudflare-workers@4346

@rivetkit/framework-base

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/framework-base@4346

@rivetkit/next-js

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/next-js@4346

@rivetkit/react

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/react@4346

rivetkit

pnpm add https://pkg.pr.new/rivet-dev/rivet/rivetkit@4346

@rivetkit/sql-loader

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sql-loader@4346

@rivetkit/sqlite-vfs

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sqlite-vfs@4346

@rivetkit/traces

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/traces@4346

@rivetkit/workflow-engine

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/workflow-engine@4346

@rivetkit/virtual-websocket

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/virtual-websocket@4346

@rivetkit/engine-runner

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner@4346

@rivetkit/engine-runner-protocol

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner-protocol@4346

commit: 664b192