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> {}

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)