---
title: "Errors: exceptions of the common API"
description: "RobotControllerException, ControllerRefusedException, FeatureNotSupportedException and RouteUnavailableException: when they are thrown, how to catch them, the protocols of a failed Connect, and IsAvailable to avoid them."
---

# Errors: exceptions of the common API

The methods of the common API throw four exceptions of the namespace `UnderAutomation.Robotics.Controllers`. `RobotControllerException` is the base class, and `FeatureNotSupportedException`, `RouteUnavailableException` and `ControllerRefusedException` derive from it. Each exception tells you what to do: change the call, change the connection settings, or try again in another state of the controller. `IsAvailable` of each service lets you avoid the first two.

![Which exception a call throws. A failed Connect throws RobotControllerException, with the result of each protocol.](/robotics/documentation/diagrams/error-flow.svg)

## The exceptions

| Exception | When it is thrown | What to do |
| --- | --- | --- |
| `RobotControllerException` | `Connect` failed, or the route of the method failed. The inner exception is the exception of the brand SDK. | Read `Protocols` after a failed `Connect`, and the inner exception after a failed call. |
| `FeatureNotSupportedException` | The brand of the controller has no route for the method. | Use another method, or ask `IsAvailable` first. The method does not work on this brand. |
| `RouteUnavailableException` | The method has routes on this brand, but none of them can be used: the controller is not connected, or the protocols of the routes are disabled or did not answer at the connection. | Read the message, which says what to enable. Enable the protocol in the connection parameters, then connect again. |
| `ControllerRefusedException` | The controller received the command and refused it. | Read `Answer`, the text of the answer of the controller. The connection is still good, and the command can work later, in another state of the controller. |

## Prerequisites

- A `RobotController`. `Connect` can throw `RobotControllerException` too: see below.
- The license of the brand of the controller, or the 30 day trial. A call without a valid license throws the `InvalidLicenseException` of the brand, not an exception of this page. See [Licensing](/robotics/documentation/license).

## Brand support

Two of the exceptions depend on the brand and on the routing. The page of each service has a table of the protocol that each method uses on each brand. A method with no route on the brand throws `FeatureNotSupportedException`. A method whose routes are all off throws `RouteUnavailableException`. The page [Routing](/robotics/documentation/routing) explains how the library chooses a route, and which routes you have to enable yourself.

`IsAvailable` returns false in both cases. The other two exceptions do not depend on the brand: the controller refused the command, or the route failed.

## Example

### Catch the exceptions of a call

Put the derived exceptions before `RobotControllerException`: it catches all of them.

**C# : ErrorsHandle**
```csharp
using UnderAutomation.Robotics.Controllers;

public class ErrorsHandle
{
    static void Main()
    {
        RobotController robot = new RobotController();
        robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));

        /**/
        try
        {
            robot.Program.Start("MAIN");
        }
        catch (ControllerRefusedException ex)
        {
            // The controller received the command and refused it: the connection is still good
            Console.WriteLine($"{ex.Feature} refused by the controller: {ex.Answer}");
        }
        catch (FeatureNotSupportedException ex)
        {
            Console.WriteLine($"{ex.Feature} is not supported on {ex.BrandName}");
        }
        catch (RouteUnavailableException ex)
        {
            // The message says what to enable
            Console.WriteLine(ex.Message);
        }
        catch (RobotControllerException ex)
        {
            // The route failed: the inner exception is the exception of the brand SDK
            Console.WriteLine($"{ex.Feature} failed with the route {ex.Route}: {ex.InnerException?.Message}");
        }
        /**/

        robot.Disconnect();
    }
}
```

**Python : ErrorsHandle**
```python
from underautomation.robotics.controllers.robot_controller import RobotController
from underautomation.robotics.controllers.robot_connection_parameters import RobotConnectionParameters
from UnderAutomation.Robotics.Controllers import (
    ControllerRefusedException,
    FeatureNotSupportedException,
    RobotControllerException,
    RouteUnavailableException,
)

robot = RobotController()
robot.connect(RobotConnectionParameters.create("fanuc", "192.168.0.1", ""))

##
try:
    robot.program.start("MAIN")
except ControllerRefusedException as ex:
    # The exceptions come from the .NET runtime, so their members keep their original names.
    # The controller received the command and refused it: the connection is still good
    print(f"{ex.Feature} refused by the controller: {ex.Answer}")
except FeatureNotSupportedException as ex:
    print(f"{ex.Feature} is not supported on {ex.BrandName}")
except RouteUnavailableException as ex:
    # The message says what to enable
    print(ex.Message)
except RobotControllerException as ex:
    # The route failed: the inner exception is the exception of the brand SDK
    inner = ex.InnerException.Message if ex.InnerException is not None else ""
    print(f"{ex.Feature} failed with the route {ex.Route}: {inner}")
##

robot.disconnect()
```

In Python, the exceptions are the .NET classes. Import them from `UnderAutomation.Robotics.Controllers`, as in the example, and use the .NET names of their members (`ex.Feature`, `ex.Message`, `ex.InnerException`). The classes with the same names in `underautomation.robotics.controllers` are not the exceptions that the calls throw.

### Avoid the exceptions with IsAvailable

`IsAvailable` returns true when the method can be called on the connected controller. The answer depends on the brand, on the routing settings and on the protocols that answered at the connection, not on the state of the controller. Use it to hide an action in a user interface, or to choose another method. A true answer does not mean that the call works: the controller can still refuse it.

**C# : RoutingAvailability**
```csharp
using UnderAutomation.Robotics.Controllers;

public class RoutingAvailability
{
    static void Main()
    {
        RobotController robot = new RobotController();
        robot.Connect(RobotConnectionParameters.Create("staubli", "192.168.0.254"));

        /**/
        // False when the brand has no route for the method, or no protocol of the route answered
        if (robot.State.IsAvailable(StateFeature.Read))
        {
            Console.WriteLine(robot.State.Read().Mode);
        }

        try
        {
            robot.State.Read();
        }
        catch (FeatureNotSupportedException ex)
        {
            Console.WriteLine($"{ex.Feature} is not supported on {ex.BrandName}");
        }
        catch (RouteUnavailableException ex)
        {
            Console.WriteLine($"{ex.Feature}: {ex.Message}");
        }
        /**/

        robot.Disconnect();
    }
}
```

**Python : RoutingAvailability**
```python
from underautomation.robotics.controllers.robot_controller import RobotController
from underautomation.robotics.controllers.robot_connection_parameters import RobotConnectionParameters
from underautomation.robotics.controllers.state_feature import StateFeature
from UnderAutomation.Robotics.Controllers import FeatureNotSupportedException, RouteUnavailableException

robot = RobotController()
robot.connect(RobotConnectionParameters.create("staubli", "192.168.0.254", ""))

##
# False when the brand has no route for the method, or no protocol of the route answered
if robot.state.is_available(StateFeature.Read):
    print(robot.state.read().mode.name)

try:
    robot.state.read()
except FeatureNotSupportedException as ex:
    # The exceptions come from the .NET runtime, so their members keep their original names
    print(f"{ex.Feature} is not supported on {ex.BrandName}")
except RouteUnavailableException as ex:
    print(f"{ex.Feature}: {ex.Message}")
##

robot.disconnect()
```

**Matlab : RoutingAvailability**
```matlab
NET.addAssembly(fullfile(pwd, 'net48', 'UnderAutomation.Robotics.dll'));
import UnderAutomation.Robotics.Controllers.*

robot = RobotController();
robot.Connect(RobotConnectionParameters.Create('staubli', '192.168.0.254', ''));

%%
% False when the brand has no route for the method, or no protocol of the route answered
if robot.State.IsAvailable(StateFeature.Read)
    state = robot.State.Read();
    disp(char(state.Mode.ToString()));
end

try
    robot.State.Read();
catch e
    % ExceptionObject is the .NET exception, for example a FeatureNotSupportedException
    if isa(e, 'NET.NetException')
        disp(char(e.ExceptionObject.Message));
    else
        rethrow(e);
    end
end
%%

robot.Disconnect();
```

### Read the protocols when Connect fails

When `Connect` fails, `RobotControllerException.Protocols` has the result of each protocol of the brand, in the order of the brand. The array is empty for the other errors. A protocol that was not tested before the failure is `NotTested`.

**C# : ConnectErrors**
```csharp
using UnderAutomation.Robotics.Controllers;

public class ConnectErrors
{
    static void Main()
    {
        /**/
        RobotController robot = new RobotController();

        try
        {
            robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));
        }
        catch (RobotControllerException ex)
        {
            Console.WriteLine(ex.Message);

            // Result of each protocol: open, no answer, authentication failed, disabled...
            foreach (ProtocolInfo protocol in ex.Protocols)
                Console.WriteLine($"{protocol.DisplayName}: {protocol.Status} {protocol.Error}");
        }
        /**/
    }
}
```

**Python : ConnectErrors**
```python
from underautomation.robotics.controllers.robot_controller import RobotController
from underautomation.robotics.controllers.robot_connection_parameters import RobotConnectionParameters
from UnderAutomation.Robotics.Controllers import RobotControllerException

##
robot = RobotController()

try:
    robot.connect(RobotConnectionParameters.create("fanuc", "192.168.0.1", ""))
except RobotControllerException as ex:
    # The exception comes from the .NET runtime, so its members keep their original names
    print(ex.Message)

    # Result of each protocol: open, no answer, authentication failed, disabled...
    for protocol in ex.Protocols:
        print(f"{protocol.DisplayName}: {protocol.Status} {protocol.Error}")
##
```

## Reference

In Python, the members of the exceptions keep the .NET names. `IsAvailable` is `is_available(...)` on each service, and the enum members keep their names.

### Members

`Message` and `InnerException` are the members of `Exception`. When the method was sent to the controller and failed, `InnerException` is the exception of the brand SDK.

**Members of Controllers.RobotControllerException**
```csharp
public class RobotControllerException : Exception, ISerializable, _Exception {
    // Path of the method, for example "Program.Start". Empty when the error is not related to one method.
    public string Feature { get; }

    // When <code>Connect</code> failed: the result of each protocol of the brand, in the order of the brand (no answer, credentials refused...).
    // A protocol that was not tested before the failure is <xref href="UnderAutomation.Robotics.Controllers.ProtocolStatus.NotTested" data-throw-if-not-resolved="false"></xref>. Empty for the other errors.
    public ProtocolInfo[] Protocols { get; }

    // Route used by the method. Empty when no route was used.
    public string Route { get; }
}
```

**Members of Controllers.FeatureNotSupportedException**
```csharp
public class FeatureNotSupportedException : RobotControllerException, ISerializable, _Exception {
    // Name of the brand of the controller
    public string BrandName { get; }
}
```

**Members of Controllers.ControllerRefusedException**
```csharp
public class ControllerRefusedException : RobotControllerException, ISerializable, _Exception {
    // Text of the answer of the controller, for example an alarm code and its message. Empty when the controller gave no text.
    public string Answer { get; }
}
```

`RouteUnavailableException` has no member of its own. Its message names the method and says what to enable.

### ProtocolInfo

**Members of Controllers.ProtocolInfo**
```csharp
public sealed class ProtocolInfo {
    // Name of the protocol for the messages, for example "FTP"
    public string DisplayName { get; }

    // Message of the error when the protocol did not answer or refused the login. Empty otherwise.
    public string Error { get; }

    // Name of the protocol, as in the routing settings and in <xref href="UnderAutomation.Robotics.Controllers.RouteInfo.Protocol" data-throw-if-not-resolved="false"></xref>, for example "Ftp"
    public string Protocol { get; }

    // Reply code of the server when the protocol refused the connection or the login and gave a code, for example the FTP reply code 530 or the HTTP status code 401.
    // 0 when there is no code.
    public int ReplyCode { get; }

    // Result of the connection of the protocol
    public ProtocolStatus Status { get; }

    public override string ToString()
}
```

**Members of Controllers.ProtocolStatus**
```csharp
public enum ProtocolStatus {
    // The protocol answered and refused the user name or the password
    AuthenticationFailed = 4

    // Forbidden by the routing settings, or, in <xref href="UnderAutomation.Robotics.Controllers.ProtocolSelection.Explicit" data-throw-if-not-resolved="false"></xref> mode, not enabled in the connect parameters
    Disabled = 5

    // The protocol did not answer: controller not reachable, function or option not enabled on the controller, wrong port
    NoAnswer = 3

    // Opened by the automatic mode, then closed because no method uses it
    NotNeeded = 7

    // Never opened automatically (the protocol has effects on the controller), and not enabled in the connect parameters
    NotProbed = 6

    // Not tested: no method needed this protocol, or the connection stopped before it
    NotTested = 1

    // Connected, and the login was accepted when the protocol has one
    Open = 2

    // Not known: default value, never given by the routing
    Unknown = 0
}
```

### Other exceptions

- `ArgumentException` or a derived exception: an invalid argument, thrown as it is. Nothing is retried and no other route is tried.
- `ArgumentOutOfRangeException`: `IsAvailable` throws only this one, for a value that is not in the enum.
- `OperationCanceledException`: a transfer of the [File](/robotics/documentation/file) service with a cancellation token was cancelled.
- `InvalidLicenseException` of the brand: the license is not valid. See [Licensing](/robotics/documentation/license).

A call never retries and never tries another route after a failure. The first error is the one that you get.

## What to read next

- [Routing](/robotics/documentation/routing): see which protocol answers each method, and enable a route.
- [Connect to your robot](/robotics/documentation/connect): the connection parameters.
- [Program](/robotics/documentation/program): start a program, a call that can be refused by the controller.