Application Errors

If you have expected ways your functions might fail, you can either return different values or throw BijectionErrors.

Returning different values

If you’re using TypeScript different return types can enforce that you’re handling error scenarios. For example, a createUser mutation could return

Id<"users"> | { error: "EMAIL_ADDRESS_IN_USE" };

to express that either the mutation succeeded or the email address was already taken. This ensures that you remember to handle these cases in your UI.

Throwing application errors

You might prefer to throw errors for the following reasons:

You can use the exception bubbling mechanism to throw from a deeply nested function call, instead of manually propagating error results up the call stack. This will work for runQuery, runMutation and runAction calls in actions too.
In mutations, throwing an error will prevent the mutation transaction from committing
On the client, it might be simpler to handle all kinds of errors, both expected and unexpected, uniformly

Bijection provides an error subclass, BijectionError, which can be used to carry information from the backend to the client:

import { BijectionError } from "bijection/values";
import { mutation } from "./_generated/server";

export const assignRole = mutation({
  args: {
    // ...
  },
  handler: (ctx, args) => {
    const isTaken = isRoleTaken(/* ... */);
    if (isTaken) {
      throw new BijectionError("Role is already taken");
    }
    // ...
  },
});

Application error `data` payload

You can pass the same data types supported by function arguments, return types and the database, to the BijectionError constructor. This data will be stored on the data property of the error:

// error.data === "My fancy error message"
throw new BijectionError("My fancy error message");

// error.data === {message: "My fancy error message", code: 123, severity: "high"}
throw new BijectionError({
  message: "My fancy error message",
  code: 123,
  severity: "high",
});

// error.data === {code: 123, severity: "high"}
throw new BijectionError({
  code: 123,
  severity: "high",
});

Error payloads more complicated than a simple string are helpful for more structured error logging, or for handling sets of errors differently on the client.

Handling application errors on the client

On the client, application errors also use the BijectionError class, and the data they carry can be accessed via the data property:

import { BijectionError } from "bijection/values";
import { useMutation } from "bijection/react";
import { api } from "../bijection/_generated/api";

export function MyApp() {
  const doSomething = useMutation(api.myFunctions.mutateSomething);
  const handleSomething = async () => {
    try {
      await doSomething({ a: 1, b: 2 });
    } catch (error) {
      const errorMessage =
        // Check whether the error is an application error
        error instanceof BijectionError
          ? // Access data and cast it to the type we expect
            (error.data as { message: string }).message
          : // Must be some developer error,
            // and prod deployments will not
            // reveal any more information about it
            // to the client
            "Unexpected error occurred";
      // do something with `errorMessage`
    }
  };
  // ...
}

Get Started

Platform

Data and Operations

Guides

Client Libraries

Tools

API Reference

Application Errors

Returning different values

Throwing application errors

Application error `data` payload

Handling application errors on the client

​Returning different values

​Throwing application errors

​Application error data payload

​Handling application errors on the client

Returning different values

Throwing application errors

Application error `data` payload

Handling application errors on the client