refactor(frontend): better gateway errors

[jog1t]

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[jog1t]

• fix(frontend): entry deduplication #5061
• [slop]feat(frontend): enable compute, add historical logs #5059
• chore: regenerate sdk #5036
• feat(frontend): allow creating serverfull instances during onboarding #5035
• feat(frontend): add provider icons #5034
• refactor(forntend): improve providers table #5033
• fix(frontend): missing provider configuration right after adding it #5032
• refactor(frontend): datacenter aware provider configuration #5031
• feat(frontend): allow local->staging tunnel in dev #5030
• refactor(frontend): better gateway errors #5029 👈 (View in Graphite)
• feat(frontend): rbac token notice for the engine #5028
• fix(frontend): build ladle correctly #5027
• feat(frontend): improve runners errors ui #5026
• fix(frontend): 404 navigation issues #5025
• fix(frontend): ns aware navigation #5024
• fix(frontend): navigate only by using actor ids #5023
• feat(frontend): add serverless check when editing the runner config #4961 : 1 other dependent PR (#4964 )
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

Code Review: refactor(frontend): better gateway errors

Overview

This PR significantly improves how the inspector surfaces gateway/engine errors to users. Key changes:

• Introduces a Zod-validated EngineErrorBody schema to safely parse structured engine errors
• Refactors buildInspectorTokenErrorMessage into distinct sub-components (OutdatedRivetKit, MissingInspectorToken, EngineErrorBlock)
• Lifts the version-outdated check to run first, independently of which HTTP error occurred
• Adds a dev-only MSW mocking surface (?mock=1) for agent-driven error UI testing
• Ships 15+ Ladle stories covering every inspector error scenario

Overall the change is a clear improvement in both UX and code clarity. A few things worth noting below.

---

Issues

EngineErrorBlock may double-render the message

EngineErrorBlock renders body.message in a paragraph tag and then passes the full body object to ErrorDetails. If ErrorDetails also renders the message field inline, the message appears twice. If ErrorDetails is a collapsible raw-dump panel this is intentional and fine, but worth verifying.

package.json indentation changed from tabs to spaces

The file was reformatted from hard tabs to 2-space indentation as a side-effect of this PR. Mixing a whitespace-only reformat into a functional PR makes the diff harder to review. It also introduced a missing newline at end of file at line 346.

mockServiceWorker.js is served in production builds

The file lives in public/ and is therefore included in production bundles. It is inert since agent-mocks.ts only registers the worker when import.meta.env.DEV and ?mock=1 is in the URL, so there is no functional concern. This is the standard MSW recommendation; just worth noting for future contributors.

Version check now takes precedence over all errors, including 401/403

The old code checked the version only inside the statusCode === 404 branch. The new code checks version first regardless of status code, so a 401/403/503 response shows "RivetKit is outdated" instead of the auth/gateway error if the version is below minimum. The comment explains this is intentional and it is probably the right call. Worth confirming whether this could hide a legitimate auth misconfiguration in self-hosted environments where operators might run mixed versions.

---

Minor Suggestions

• The mt-2 on the outermost div in EngineErrorBlock is redundant since the parent is already a flex flex-col gap-2 container.
• STORAGE_KEY in agent-mocks.ts could collide across browser tabs pointing at different projects on the same localhost origin. A per-project prefix would eliminate the ambiguity.

---

Positives

• The Zod schema for engine error bodies is the right approach; no more manual typeof chains.
• Exporting buildInspectorTokenErrorMessage and OutdatedInspector specifically for Ladle is clean; they are not part of the public API otherwise.
• The Ladle story gallery is excellent. Every error code path is covered with realistic payloads sourced directly from the engine error source files.
• The MSW setup is well-designed: dev-only gating, sessionStorage persistence across reloads, clean window.__rivetMock / __rivetClearMocks API, and a zero-cost prod build.
• The CLAUDE.md entry for the mock surface is precise and actionable.

[jog1t]

Merge activity

• May 15, 7:36 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• May 15, 7:50 PM UTC: Graphite rebased this pull request as part of a merge.
• May 15, 7:50 PM UTC: @jog1t merged this pull request with Graphite.