From cabafd7e6052a9683726316c1d5f285993a6a4f4 Mon Sep 17 00:00:00 2001 From: Ashutosh Anand Date: Wed, 3 Jun 2026 14:45:23 +0530 Subject: [PATCH 1/3] docs: Document custom serializable exceptions --- docs/06-concepts/04-exceptions.md | 53 +++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/docs/06-concepts/04-exceptions.md b/docs/06-concepts/04-exceptions.md index f84e8379..3ccc9edd 100644 --- a/docs/06-concepts/04-exceptions.md +++ b/docs/06-concepts/04-exceptions.md @@ -53,6 +53,59 @@ catch(e) { } ``` +### Custom serializable exception classes + +Use the `exception` keyword in a Serverpod model file when you define a new +exception for your project. If you already have a Dart exception class in a +package shared by the server and client, the class must implement +`SerializableException` for Serverpod to send it to the client. Otherwise, +Serverpod treats the exception as an internal server error. + +```dart +import 'package:serverpod_serialization/serverpod_serialization.dart'; + +class UserFacingException implements SerializableException { + final String message; + final String? code; + + UserFacingException({ + required this.message, + this.code, + }); + + factory UserFacingException.fromJson(Map json) { + return UserFacingException( + message: json['message'] as String, + code: json['code'] as String?, + ); + } + + @override + Map toJson() { + return { + 'message': message, + 'code': code, + }; + } + + @override + String toString() => message; +} +``` + +The class must also be known to Serverpod's generated serialization manager. +Register it in the server project's `config/generator.yaml`, then run +`serverpod generate`: + +```yaml +extraClasses: + - package:my_project_shared/my_project_shared.dart:UserFacingException +``` + +The `SerializableException` interface marks the exception as safe to serialize +to the client. The `extraClasses` entry lets Serverpod generate the +deserialization code needed to reconstruct the exception on the client. + ### Default values in exceptions Serverpod allows you to specify default values for fields in exceptions, similar to how it's done in models using the `default` and `defaultModel` keywords. If you're unfamiliar with how these keywords work, you can refer to the [Default Values](models#default-values) section in the [Working with Models](models) documentation. From 70797847fe862cd3dc05ca5a567a550b09d1f314 Mon Sep 17 00:00:00 2001 From: Ashutosh Anand Date: Thu, 4 Jun 2026 09:39:21 +0530 Subject: [PATCH 2/3] docs: refine serializable exception example --- docs/06-concepts/04-exceptions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/06-concepts/04-exceptions.md b/docs/06-concepts/04-exceptions.md index 3ccc9edd..071a137e 100644 --- a/docs/06-concepts/04-exceptions.md +++ b/docs/06-concepts/04-exceptions.md @@ -64,7 +64,7 @@ Serverpod treats the exception as an internal server error. ```dart import 'package:serverpod_serialization/serverpod_serialization.dart'; -class UserFacingException implements SerializableException { +class UserFacingException implements SerializableException, Exception { final String message; final String? code; @@ -99,7 +99,7 @@ Register it in the server project's `config/generator.yaml`, then run ```yaml extraClasses: - - package:my_project_shared/my_project_shared.dart:UserFacingException + - "package:my_project_shared/my_project_shared.dart:UserFacingException" ``` The `SerializableException` interface marks the exception as safe to serialize From 506bb8b242b8ffcb090c670a82322d2ea0e7d056 Mon Sep 17 00:00:00 2001 From: Ashutosh Anand Date: Thu, 4 Jun 2026 09:44:03 +0530 Subject: [PATCH 3/3] docs: keep serializable exception example idiomatic --- docs/06-concepts/04-exceptions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/06-concepts/04-exceptions.md b/docs/06-concepts/04-exceptions.md index 071a137e..3ccc9edd 100644 --- a/docs/06-concepts/04-exceptions.md +++ b/docs/06-concepts/04-exceptions.md @@ -64,7 +64,7 @@ Serverpod treats the exception as an internal server error. ```dart import 'package:serverpod_serialization/serverpod_serialization.dart'; -class UserFacingException implements SerializableException, Exception { +class UserFacingException implements SerializableException { final String message; final String? code; @@ -99,7 +99,7 @@ Register it in the server project's `config/generator.yaml`, then run ```yaml extraClasses: - - "package:my_project_shared/my_project_shared.dart:UserFacingException" + - package:my_project_shared/my_project_shared.dart:UserFacingException ``` The `SerializableException` interface marks the exception as safe to serialize