Error Handling
An action can fail because its input is invalid or because something went wrong on the server. Mountaineer exposes typed errors to the client so you can handle expected failures and let unexpected ones propagate.
Client->Server exceptions
When a sideeffect or passthrough request fails, the generated async function throws an error. This button deliberately sends a string where the action expects an integer:
<button
onClick={async () => {
await serverState.increment_count({
requestBody: {
// @ts-ignore
count: "invalid payload",
},
});
}}
>
Invalid Increment
</button>
Pydantic rejects the value with a ValidationError, and the server returns HTTP 422. Catch the generated HTTPValidationErrorException on the client:
import { HTTPValidationErrorException } from "./_server/actions";
...
<button
className="rounded-md bg-blue-500 p-2 text-white"
onClick={async () => {
try {
await serverState.increment_count({
requestBody: {
// @ts-ignore
count: "invalid payload",
},
});
} catch (error) {
if (error instanceof HTTPValidationErrorException) {
console.log(
"Validation Error",
error.body.detail?.[0].loc,
error.body.detail?.[0].msg,
);
} else {
throw error;
}
}
}}
>
Invalid Increment
</button>
Mountaineer exports the error class from _server/actions. The instanceof check narrows the error's type, giving you typed access to its payload in error.body. This example logs the invalid field and validation message:
Validation Error (2) ['body', 'count'] Input should be a valid integer, unable to parse string as an integer
Generated error classes extend FetchErrorBase with the payload type for that error:
class HTTPValidationErrorException extends FetchErrorBase<HTTPValidationError> {}
For more information on error typehinting and custom handling, see the FastAPI documentation.
Custom Errors
Every action includes the HTTP 422 validation error. For application-specific failures, subclass APIException and declare it on the action:
from mountaineer.exceptions import APIException
class LoginInvalid(APIException):
status_code = 401
invalid_reason: str
class LoginController(ControllerBase):
...
@passthrough(exception_models=[LoginInvalid])
def login(self, login_payload: LoginRequest):
raise LoginInvalid(invalid_reason="Login not implemented")
Provide all the exceptions that your function may throw to @passthrough(exception_models=[]). The @sideeffect decorator accepts the same argument.
Mountaineer generates a corresponding client error class that you can catch with instanceof.
SSR timeouts
Server-side rendering executes your view's JavaScript in V8. An expensive calculation or infinite loop can prevent a render from finishing, so Mountaineer provides:
- Debug logs with each page's render duration.
- Warning logs when a render exceeds the warning threshold.
- A hard timeout that terminates the JavaScript executor and returns an error to the client.
SSR exceptions
If JavaScript throws during rendering, Mountaineer raises mountaineer.ssr.V8RuntimeError and logs the V8 stack trace. Source maps translate the compiled locations back to files in your view directory:
{"level": "ERROR", "name": "mountaineer.logging", "message": "Exception encountered in ComplexController rendering"}
ERROR: Exception in ASGI application
Traceback (most recent call last):
File "/Users/piercefreeman/projects/mountaineer/mountaineer/ssr.py", line 37, in render_ssr
render_result = mountaineer_rs.render_ssr(
^^^^^^^^^^^^^^^^^^^^
...
File "/Users/piercefreeman/projects/mountaineer/mountaineer/ssr.py", line 43, in render_ssr
raise V8RuntimeError(e)
mountaineer.ssr.V8RuntimeError: Error calling function 'Index': Error: Example client error
Stack: Error: Example client error
at Page (./my_website/views/app/complex/page.tsx:41:10)
at renderWithHooks (./my_website/views/node_modules/react-dom/cjs/react-dom-server-legacy.browser.development.js:5660:15)
at renderIndeterminateComponent (./my_website/views/node_modules/react-dom/cjs/react-dom-server-legacy.browser.development.js:5733:14)
at renderElement (<anonymous>:6537:17)
at renderNodeDestructiveImpl (<anonymous>:6642:19)
at renderNodeDestructive (./my_website/views/node_modules/react-dom/cjs/react-dom-server-legacy.browser.development.js:6078:13)
at renderIndeterminateComponent (<anonymous>:6417:17)
at renderElement (<anonymous>:6537:17)
at renderNodeDestructiveImpl (<anonymous>:6642:19)
at renderNodeDestructive (./my_website/views/node_modules/react-dom/cjs/react-dom-server-legacy.browser.development.js:6078:13)