Overhaul error handling across the app

[kmcginnes]

Description

Error handling in Graph Explorer is a set of independent decisions rather than a system. Each domain error rolls its own shape, utils/createDisplayError.ts grew a ~190-line if-chain that silently degrades to "Something went wrong" when a case is missed, connector boundaries hand back unchecked casts, and untrusted imported files can throw from inside a component and leave the app broken across reloads. Tests assert errors three different ways and the guidance in docs/agents/testing.md no longer matches any of them.

None of these is large alone. Together they are why a new error type costs a hand-written branch in two display helpers, why a 403 shows an opaque JSON blob, and why a bad color in a shared styling file is unrecoverable.

This initiative gathers the existing backlog so the pieces get decided together instead of one PR at a time. It is a container: track its children, not this issue.

Themes

Error modelling and contract — one shape for domain errors, so the display and details paths stop needing a branch per type.

• Consolidate domain error types behind a shared base class #2163 Consolidate domain error types behind a shared base class
• Replace the hand-rolled isErrorResponse guard with Zod validation #2173 Replace the hand-rolled isErrorResponse guard with Zod validation

Validation at boundaries — Zod where untrusted data enters: connector responses, imported styling and connection files, user-entered limits.

• Establish the shape of database error responses across engines and Neptune versions #2172 Establish the shape of database error responses across engines and Neptune versions
• Validate connector fetch boundaries with Zod and brand label types #2078 Validate connector fetch boundaries with Zod and brand label types
• Invalid color in an imported styling file permanently breaks the graph and schema views #2114 Invalid color in an imported styling file permanently breaks the graph and schema views
• Blank edge style colors are not dropped at the read boundary #2110 Blank edge style colors are not dropped at the read boundary
• Clean up summary API usage #1287 Clean up summary API usage
• Clearing the neighbor expansion limit field silently expands without a limit #2068 Clearing the neighbor expansion limit field silently expands without a limit

User-facing messaging — what a user actually reads when something fails, and getting notifications out of React-only code paths.

• 403 errors show an unfriendly "Network Response 403" message #1977 403 errors show an unfriendly "Network Response 403" message
• Bad formatting of error details when HTML is returned #891 Bad formatting of error details when HTML is returned
• [Project] Allow sending toast notifications outside of React code #359 Allow sending toast notifications outside of React code

Recovery and retry — surviving a failure rather than blanking the app, and retrying at the right granularity.

• Explicit bootstrap gate for persisted data preload #1833 Explicit bootstrap gate for persisted data preload
• Back up from in-memory state so recovery includes the failed write #1858 Back up from in-memory state so recovery includes the failed write
• Retry individual queries in schema sync process #1214 Retry individual queries in schema sync process
• 500 errors when restoring previous session in SageMaker deployment #1767 500 errors when restoring previous session in SageMaker deployment

Diagnostics — enough context logged to explain a failure after the fact.

• Log connection details when request fails #1210 Log connection details when request fails
• Improve client-to-server logging endpoint #1635 Improve client-to-server logging endpoint

Testing conventions — one documented way to assert errors, derived from whatever base type the modelling work lands on.

• Define an app-wide convention for asserting domain and validation errors in tests #2174 Define an app-wide convention for asserting domain and validation errors in tests

Notes

Several children are older backlog items with no recent activity (#359, #891, #1210, #1214, #1287, #1635, #1767). They are in scope but worth confirming as still wanted before being picked up. Most also carry no audience label.

#1850 was closed as already delivered by #2162.

Deliberately excluded, for the record: #1045 (proxy retry env vars, config knobs rather than error-handling design), #1217 (diagnostic context for all queries, not failures), #1209 (connection detail UI enhancement), #2060 and #1557 (domain logic and render-ordering bugs that merely manifest as messages), #1327 (ordinary form validation).

Important

Internal only — this issue is maintained by the core team and is not accepting external contributions.