Api

createSafeActionClient

Server builder factory and unexpected-error mapper reference.

createSafeActionClient

import { createSafeActionClient } from '#safe-action'

const actionClient = createSafeActionClient({
  handleServerError(error) {
    console.error('Action failed:', error)
    return 'Something went wrong. Please try again.'
  },
})
OptionTypeBehavior
handleServerError(error: Error) => TServerErrorMaps unexpected exceptions to a public error value; defaults to a generic string

ActionError intentionally returns its own public message. ActionValidationError / returnValidationErrors() return validation errors. Neither passes through the unexpected-error mapper. A throwing mapper uses a generic fallback.

The return value is an immutable builder with schema, outputSchema, use, metadata, and action methods. Create branches for shared concerns; methods do not mutate their source builder.

The default server-error type is string. A custom mapper can infer another type, but intentional ActionError messages and client transport failures still use strings at runtime. Keep a string error contract if your consumer needs one uniform runtime shape.

Copyright © 2026