---
title: "Exceptions"
url: https://docs.zeroc.com/ice/3.8/slice/exceptions
docs_index: https://docs.zeroc.com/llms.txt
---

> For an index of every page, see [llms.txt](https://docs.zeroc.com/llms.txt).

# Exceptions

Parts of this page are for some programming languages only, and name them. For one language's text alone, see [C++](https://docs.zeroc.com/ice/3.8/slice/exceptions/cpp.md), [C#](https://docs.zeroc.com/ice/3.8/slice/exceptions/csharp.md), [Java](https://docs.zeroc.com/ice/3.8/slice/exceptions/java.md), [JavaScript](https://docs.zeroc.com/ice/3.8/slice/exceptions/js.md), [MATLAB](https://docs.zeroc.com/ice/3.8/slice/exceptions/matlab.md), [PHP](https://docs.zeroc.com/ice/3.8/slice/exceptions/php.md), [Python](https://docs.zeroc.com/ice/3.8/slice/exceptions/python.md), [Ruby](https://docs.zeroc.com/ice/3.8/slice/exceptions/ruby.md), and [Swift](https://docs.zeroc.com/ice/3.8/slice/exceptions/swift.md).

## Exception Syntax and Semantics

A Slice exception defines an error that an operation can report to its caller. Exceptions defined in Slice are called *user exceptions*, to distinguish them from the [exceptions of the Ice runtime](https://docs.zeroc.com/ice/3.8/runtime/local-and-dispatch-exceptions.md). For example:

```slice
struct TimeOfDay
{
    short hour;         // 0 - 23
    short minute;       // 0 - 59
    short second;       // 0 - 59
}

exception TimeException {} // Empty exceptions are legal

exception RangeException
{
    TimeOfDay errorTime;
    TimeOfDay minTime;
    TimeOfDay maxTime;
}
```

A user exception is much like a structure in that it contains a number of fields. However, unlike structures, exceptions can have zero fields, that is, be empty. Like classes, user exceptions support inheritance and may include [optional fields](https://docs.zeroc.com/ice/3.8/slice/fields.md).

## Exception Specification in Operations

Exceptions allow you to return an arbitrary amount of error information to the client if an error condition arises in the implementation of an operation. Operations use an exception specification to indicate the exceptions that may be returned to the client:

```slice
interface Clock
{
    idempotent TimeOfDay getTime();
    idempotent void setTime(TimeOfDay time)
        throws RangeException, TimeException;
}
```

`setTime` can throw a `RangeException` or a `TimeException`. A `RangeException` reports the `TimeOfDay` value that caused the error and the range of legal values; a `TimeException` reports only that `setTime` failed.

To indicate that an operation does not throw any user exception, simply omit the exception specification. (There is no empty exception specification in Slice.)

### Restrictions for User Exceptions

An exception is not a data type: you cannot use an exception as the type of a parameter, a return value, a field, a sequence element, or a dictionary key or value. Conversely, an exception specification lists only exceptions.

## Exception Inheritance

Slice exceptions support single inheritance. A derived exception inherits the fields of its base exception and can add its own, but cannot redefine an inherited field:

```slice
exception BaseException
{
    string reason;
}

exception DerivedException extends BaseException
{
    int code;
}

interface Example
{
    // May throw BaseException or DerivedException
    void op() throws BaseException;
}
```

An operation can throw any exception derived from the exceptions in its exception specification: `op` can throw a `BaseException` or a `DerivedException`. The language mappings preserve the exception hierarchy, so you can catch a base exception generically or handle specific derived exceptions.

As a system evolves, new derived exceptions are often added to an existing hierarchy. Suppose that you add `FatalApplicationException` to the original definitions and redeploy the server:

```slice
exception AppException
{
    // ...
}

exception FatalApplicationException extends AppException
{
    // ...
}

interface Application
{
    void doSomething() throws AppException;
}
```

A client built with the original definition does not know `FatalApplicationException`: Ice slices the exception to `AppException`, the most-derived type this client knows.

See [Slicing Values and Exceptions](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/classes/slicing-values-and-exceptions.md) for the rules Ice follows when it slices an exception.

## Language Mapping

> **C++**
>
> A Slice exception is mapped to a C++ class with the same name. This mapping is similar to the mapping of classes.
>
> Consider the following Slice exceptions:
>
> ```slice
> module M
> {
>     exception GenericException
>     {
>         string reason;
>     }
>
>     exception BadTimeValException extends GenericException {}
> }
> ```
>
> The Slice compiler generates the following code for these exceptions:
>
> ```cpp
> class GenericException : public Ice::UserException
> {
> public:
>     GenericException() noexcept = default;
>     GenericException(std::string reason) noexcept;
>     GenericException(const GenericException&) noexcept = default;
>
>     void ice_throw() const override;
>
>     std::string reason;
> };
>
> class BadTimeValException : public GenericException
> {
> public:
>     using GenericException::GenericException;
>
>     void ice_throw() const override;
> };
> ```
>
> There are a number of things to note about this generated code:
>
> 1. The generated class `GenericException` inherits from `Ice::UserException`. `Ice::UserException` is the ultimate ancestor of all mapped exceptions. It derives indirectly from `std::exception`.
> 2. The generated class contains a public data member for each Slice field.
> 3. The generated class has a constructor that takes one argument for each data member, as well as a default constructor.
> 4. The generated class has a `noexcept` copy constructor.
> 5. The generated class has a virtual function, `ice_throw`. It is implemented by throwing `*this`.
> 6. The generated class for `BadTimeValException` derives from the generated class `GenericException`.
>
> ### Exception Printing
>
> You can print any user exception instance by calling `ice_print` on this instance. `ice_print` is defined on `Ice::Exception`. Alternatively, you can print an exception instance with operator\<\<:
>
> ```cpp
> try
> {
>    ...
> }
> catch (const M::GenericException& exception)
> {
>     cout << "Caught " << exception << endl;
> }
> ```
>
> `operator<<` just calls `Ice::Exception::ice_print`.
>
> You can use the metadata directive `"cpp:custom-print"` to tell the Slice compiler that you want to use your own custom print implementation. For example:
>
> ```slice
> ["cpp:custom-print"]
> exception GenericException { ... }
> ```
>
> The Slice compiler then generates an `ice_print` override declaration in the mapped C++ class, and you are responsible to implement this member function.

> **C#**
>
> A Slice exception is mapped to a C# class with the same name. This mapping is similar to the mapping of [classes](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/classes/csharp.md).
>
> Consider the following Slice exceptions:
>
> ```slice
> module M
> {
>     exception GenericException
>     {
>         string reason;
>     }
>
>     exception BadTimeValException extends GenericException {}
> }
> ```
>
> The Slice compiler generates the following code for these exceptions:
>
> ```csharp
> public partial class GenericException : Ice.UserException
> {
>     public string reason = "";
>
>     public GenericException(string reason) { ... }
>     public GenericException() {}
> }
>
> public partial class BadTimeValException : GenericException
> {
>       public BadTimeValException(string reason)
>           : base(reason)
>       {
>       }
>
>       public BadTimeValException() {}
> }
> ```
>
> There are a number of things to note about this generated code:
>
> 1. The generated class `GenericException` inherits from `Ice.UserException`. `Ice.UserException` is the ultimate ancestor of all mapped exceptions. It derives indirectly from `System.Exception`.
> 2. The generated class contains a public field for each Slice field.
> 3. The generated class for `BadTimeValException` derives from the generated class `GenericException`.
> 4. The generated class provides a constructor with a parameter for each field and a parameterless constructor; they are identical to the generated constructors for classes. See [C# Mapping for Classes](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/classes/csharp.md).

> **Java**
>
> A Slice exception is mapped to a Java class with the same name. This mapping is similar to the mapping of [classes](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/classes/java.md).
>
> Consider the following Slice exceptions:
>
> ```slice
> module M
> {
>     exception GenericException
>     {
>         string reason;
>     }
>
>     exception BadTimeValException extends GenericException {}
> }
> ```
>
> The Slice compiler generates the following code for these exceptions:
>
> ```java
> public class GenericException extends com.zeroc.Ice.UserException {
>     public String reason;
>
>     public GenericException() {
>         this.reason = "";
>     }
>
>     public GenericException(String reason) {
>         this.reason = reason;
>     }
>
>     // ...
> }
>
> public class BadTimeValException extends GenericException {
>     public BadTimeValException() {
>     }
>
>     public BadTimeValException(String reason) {
>         super(reason);
>     }
>
>     // ...
> }
> ```
>
> There are a number of things to note about this generated code:
>
> 1. The generated class `GenericException` inherits from `UserException`. `UserException` is the ultimate ancestor of all mapped exceptions. It’s a checked exception that derives from `java.lang.Exception`.
> 2. The generated class contains a public field for each Slice field.
> 3. The generated class for `BadTimeValException` derives from the generated class `GenericException`.
> 4. The generated class provides a constructor with a parameter for each field and a parameterless constructor; they are identical to the generated constructors for classes. See [Java Mapping for Classes](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/classes/java.md).
>
> ### Exception Specification
>
> When an Slice operation has an exception specification, the corresponding client-side and server-side methods in Java have an exception specification. This is true for all mapped methods, except the proxy `Async` methods.
>
> For example:
>
> ```slice
> interface Greeter
> {
>     ["amd"]
>     string greet(string name) throws BadNameException, GoneFishingException;
> }
> ```
>
> maps to:
>
> ```java
> // Client-side
> public interface GreeterPrx extends com.zeroc.Ice.ObjectPrx {
>     default String greet(String name)
>         throws BadNameException, GoneFishingException {
>         ...
>     }
>
>     default String greet(String name, java.util.Map<String, String> context)
>         throws BadNameException, GoneFishingException {
>         ...
>     }
>
>     // No exception specification
>     default CompletableFuture<String> greetAsync(String name) {
>         ...
>     }
>
>     default CompletableFuture<String> greetAsync(String name, java.util.Map<String, String> context) {
>         ...
>     }
> }
>
> // Server-side
> public interface Greeter extends com.zeroc.Ice.Object {
>     CompletionStage<String> greetAsync(String name, com.zeroc.Ice.Current current)
>         throws BadNameException, GoneFishingException;
> }
> ```
>
> > **Note**
> >
> > If you rename the exception or an enclosing module with `java:identifier`, or place the enclosing top-level module in another Java package with `java:package`, install a [Slice loader](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/classes/slice-loaders/java.md) in communicators that receive this exception. For `java:package` alone, setting the matching [Ice.Package.*module*](https://docs.zeroc.com/ice/3.8/property-reference/ice-properties/java.md#ice.package.module) property or [Ice.Default.Package](https://docs.zeroc.com/ice/3.8/property-reference/ice-default-properties/java.md#ice.default.package) also works.

> **JavaScript**
>
> A Slice exception is mapped to a JavaScript class with the same name. This mapping is similar to the mapping of [JavaScript Mapping for Classes](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/classes/js.md).
>
> Consider the following Slice exceptions:
>
> ```slice
> module M
> {
>     exception GenericException
>     {
>         string reason;
>     }
>
>     exception BadTimeValException extends GenericException {}
> }
> ```
>
> The Slice compiler generates the following code for these exceptions:
>
> ```js
> class GenericException extends Ice.UserException {
>     constructor(reason = "") {
>         super();
>         this.reason = reason;
>     }
>     // ...
> }
>
> class BadTimeValException extends GenericException {}
> ```
>
> ```typescript
> class GenericException extends Ice.UserException {
>     constructor(reason?: string);
>
>     reason: string;
> }
>
> class BadTimeValException extends GenericException {}
> ```
>
> There are a number of things to note about this generated code:
>
> 1. The generated class `GenericException` inherits from `Ice.UserException`. `Ice.UserException` is the ultimate ancestor of all mapped exceptions. It derives indirectly from JavaScript `Error` type.
> 2. The generated class contains a field for each Slice field.
> 3. The generated class for `BadTimeValException` derives from the generated class `GenericException`.
> 4. The generated class provides a constructor with a parameter for each field, just like [mapped classes](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/classes/js.md).

> **MATLAB**
>
> A Slice exception is mapped to a MATLAB class with the same name. This mapping is similar to the mapping of [classes](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/classes/matlab.md).
>
> Consider the following Slice exceptions:
>
> ```slice
> module M
> {
>     exception GenericException
>     {
>         string reason;
>     }
>
>     exception BadTimeValException extends GenericException {}
> }
> ```
>
> The Slice compiler generates the following code for these exceptions:
>
> ```matlab
> classdef GenericException < Ice.UserException
>     properties
>       reason (1, :) char
>     end
>     methods
>         % ...
>     end
> end
>
> classdef BadTimeValException < M.GenericException
>     methods
>         % ...
>     end
> end
> ```
>
> There are a number of things to note about this generated code:
>
> 1. The generated class `GenericException` inherits from `Ice.UserException`. `Ice.UserException` is the ultimate ancestor of all mapped exceptions. It derives indirectly from `MException`.
> 2. The generated class contains a public property for each Slice field.
> 3. The generated class for `BadTimeValException` derives from the generated class `GenericException`.
>
> > **Note**
> >
> > If you remap your exception class name or the name of the enclosing namespace with `matlab:identifier`, remember to set a custom [Slice loader](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/classes/slice-loaders/matlab.md) in communicators that receive this exception.

> **PHP**
>
> A Slice exception is mapped to a PHP class with the same name. This mapping is similar to the mapping of [classes](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/classes/php.md).
>
> Consider the following Slice exceptions:
>
> ```slice
> module M
> {
>     exception GenericException
>     {
>         string reason;
>     }
>
>     exception BadTimeValException extends GenericException {}
> }
> ```
>
> The Slice compiler generates the following code for these exceptions:
>
> ```php
> class GenericException extends \Ice\UserException
> {
>     public $reason;
>     // ...
> }
>
> class BadTimeValException extends \M\GenericException
> {
>     // ..
> }
> ```
>
> There are a number of things to note about this generated code:
>
> 1. The generated class `GenericException` inherits from `\Ice\UserException`. `\Ice\UserException` is the ultimate ancestor of all mapped exceptions. It derives indirectly from `\Exception`.
> 2. The generated class contains a public property for each Slice field.
> 3. The generated class for `BadTimeValException` derives from the generated class `GenericException`.

> **Python**
>
> A Slice exception is mapped to a Python class with the same name. This mapping is similar to the mapping of [classes](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/classes/python.md).
>
> Consider the following Slice exceptions:
>
> ```slice
> module M
> {
>     exception GenericException
>     {
>         string reason;
>     }
>
>     exception BadTimeValException extends GenericException {}
> }
> ```
>
> The Slice compiler generates the following code for these exceptions:
>
> ```py
> @dataclass
> class GenericException(UserException):
>     reason: str = ""
>
> @dataclass
> class BadTimeValException(GenericException):
>     pass
> ```
>
> There are a number of things to note about this generated code:
>
> 1. The generated classes are dataclasses, just like the mapping for classes.
> 2. The generated class `GenericException` inherits from `UserException`. `Ice.UserException` is the ultimate ancestor of all mapped exceptions. It derives indirectly from `builtins.Exception`.
> 3. The generated class contains a public field for each Slice field.
> 4. The generated class for `BadTimeValException` derives from the generated class `GenericException`.

> **Ruby**
>
> A Slice exception maps to a Ruby class with the same name, capitalized. This mapping is similar to the mapping of [classes](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/classes/ruby.md).
>
> Consider the following Slice exceptions:
>
> ```slice
> module M
> {
>     exception GenericException
>     {
>         string reason;
>     }
>
>     exception BadTimeValException extends GenericException {}
> }
> ```
>
> The Slice compiler generates the following code for these exceptions:
>
> ```ruby
> module ::M
>     class GenericException < Ice::UserException
>         attr_accessor :reason
>         # ...
>     end
>
>     class BadTimeValException < ::M::GenericException
>     # ...
>     end
> end
> ```
>
> There are a number of things to note about this generated code:
>
> 1. The generated class `GenericException` inherits from `Ice::UserException`. `Ice::UserException` is the ultimate ancestor of all mapped exceptions. It derives indirectly from `::StandardError`.
> 2. For each Slice field, the generated class contains an instance variable and accessors to read and write this variable.
> 3. The generated class for `BadTimeValException` derives from the generated class `GenericException`.

> **Swift**
>
> A Slice exception is mapped to a Swift class with the same name. This mapping is similar to the mapping of [classes](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/classes/swift.md).
>
> Consider the following Slice exceptions:
>
> ```slice
> module M
> {
>     exception GenericException
>     {
>         string reason;
>     }
>
>     exception BadTimeValException extends GenericException {}
> }
> ```
>
> The Slice compiler generates the following code for these exceptions:
>
> ```swift
> open class GenericException: Ice.UserException, @unchecked Sendable {
>     public var reason: String = ""
>
>     public required init() {}
>
>     public init(reason: String) {
>         self.reason = reason
>     }
>     // ...
> }
>
> open class BadTimeValException: GenericException, @unchecked Sendable {
>     // ...
> }
> ```
>
> There are a number of things to note about this generated code:
>
> 1. The generated class `GenericException` derives from `Ice.UserException`. The `Ice.UserException` class is the ultimate ancestor of all mapped exceptions. It conforms to the `Error` protocol.
> 2. The generated class contains a public property for each Slice field.
> 3. The generated class for `BadTimeValException` derives from the generated class `GenericException`.
> 4. The generated class provides a default initializer and a memberwise initializer; they are identical to the generated initializers for Slice classes.
>
> The generated classes conform to `Sendable` through `@unchecked Sendable`, because the `Error` protocol requires it. They are not thread-safe: do not share an exception instance between concurrent tasks.

## See Also

- [Local and Dispatch Exceptions](https://docs.zeroc.com/ice/3.8/runtime/local-and-dispatch-exceptions.md)
