Error Handling

The Eriksson Beam API uses specific exception types to indicate different error conditions. This guide covers all exception types and recommended handling strategies.

Exception Types

ErikssonBeamNotRunningException

When thrown: Eriksson Beam process is not running or not responding.

Common causes:

  • Eriksson Beam hasn't been started
  • Process crashed or was closed
  • 10-minute idle timeout exceeded
  • Process ID doesn't match a running instance

Example:

try
{
    var client = await ErikssonBeamFinder.GetFirstSupportedBeamClient(args);
}
catch (ErikssonBeamNotRunningException ex)
{
    Console.WriteLine("Eriksson Beam is not running.");
    Console.WriteLine("Please start Eriksson Beam and try again within 10 minutes.");
}

ErikssonBeamConnectionException

When thrown: Connection to Eriksson Beam failed.

Common causes:

  • Named pipe not available
  • Connection refused
  • Network/IPC issues

Example:

try
{
    var client = await ErikssonBeamClient.AttemptConnection(args);
}
catch (ErikssonBeamConnectionException ex)
{
    Console.WriteLine($"Connection failed: {ex.Message}");
    Console.WriteLine("Try restarting Eriksson Beam.");
}

ServerErrorException

When thrown: Server processed the request but returned an error.

Access error details:

catch (ServerErrorException ex)
{
    ResponseCode code = ex.Response.ResponseCode;
    string message = ex.Response.ErrorMessage;
}

Response codes:

Code Meaning
Success Operation succeeded (not thrown)
InternalServerError Unexpected server error
LicenseError Invalid or expired license key
VersionError API version mismatch
Unauthorized Not authorized for this operation
InvalidRequest Malformed or invalid request
Timeout Server-side timeout
ServerBusy Server is processing another request
Uninitialized Server not ready

Example:

try
{
    await client.PushBeamDesignerAsync("project", design);
}
catch (ServerErrorException ex)
{
    switch (ex.Response.ResponseCode)
    {
        case ResponseCode.LicenseError:
            Console.WriteLine("License validation failed.");
            Console.WriteLine("Please check your license key.");
            break;

        case ResponseCode.InvalidRequest:
            Console.WriteLine($"Invalid data: {ex.Response.ErrorMessage}");
            break;

        case ResponseCode.InternalServerError:
            Console.WriteLine($"Server error: {ex.Response.ErrorMessage}");
            break;

        default:
            Console.WriteLine($"Error ({ex.Response.ResponseCode}): {ex.Response.ErrorMessage}");
            break;
    }
}

UnexpectedMessageException

When thrown: Server sent an unexpected response type.

Common causes:

  • Protocol mismatch
  • API version incompatibility
  • Internal communication error

Resolution: This usually indicates a bug. Contact support with details.

catch (UnexpectedMessageException ex)
{
    Console.WriteLine($"Unexpected response: {ex.Message}");
    Console.WriteLine("This may indicate a version mismatch.");
}

MessageReadException

When thrown: Failed to parse server response.

Common causes:

  • Corrupted response
  • Serialization error
  • Connection interrupted during transfer

Resolution: Retry the operation. If persistent, restart Eriksson Beam.

catch (MessageReadException ex)
{
    Console.WriteLine($"Failed to read response: {ex.Message}");
    Console.WriteLine("Retrying...");
    // Implement retry logic
}

InvalidRequestException

When thrown: Client sent an invalid request.

Common causes:

  • Internal validation failure
  • Malformed request construction

Resolution: Usually indicates a bug in the API usage. Check parameters.

Standard .NET Exceptions

Exception When Thrown
ArgumentNullException Null parameter passed to method
ArgumentException Invalid parameter value (e.g., ProcessID <= 0)
ObjectDisposedException Using disposed client/launcher
OperationCanceledException Timeout exceeded
TimeoutException Connection attempts exhausted 
public async Task<bool> SafeUpdateDesign(
    ErikssonBeamClient client,
    string project,
    Action<BeamDesign> modifier)
{
    try
    {
        // Pull current design
        var design = await client.PullBeamDesignerAsync(project);

        // Apply modifications
        modifier(design);

        // Push changes
        await client.PushBeamDesignerAsync(project, design);

        return true;
    }
    catch (ErikssonBeamNotRunningException)
    {
        Console.WriteLine("Error: Eriksson Beam is not running.");
        Console.WriteLine("Start Eriksson Beam and try again.");
        return false;
    }
    catch (ServerErrorException ex) when (ex.Response.ResponseCode == ResponseCode.LicenseError)
    {
        Console.WriteLine("Error: License validation failed.");
        return false;
    }
    catch (ServerErrorException ex)
    {
        Console.WriteLine($"Server error: {ex.Response.ErrorMessage}");
        return false;
    }
    catch (OperationCanceledException)
    {
        Console.WriteLine("Error: Operation timed out.");
        Console.WriteLine("Increase IdleTimeoutMs or check connection.");
        return false;
    }
    catch (ObjectDisposedException)
    {
        Console.WriteLine("Error: Client has been disposed.");
        return false;
    }
}

Retry Strategy

For transient errors, implement retry with exponential backoff:

public async Task<T> WithRetry<T>(
    Func<Task<T>> operation,
    int maxRetries = 3,
    int initialDelayMs = 1000)
{
    int delay = initialDelayMs;

    for (int attempt = 1; attempt <= maxRetries; attempt++)
    {
        try
        {
            return await operation();
        }
        catch (ErikssonBeamConnectionException) when (attempt < maxRetries)
        {
            Console.WriteLine($"Attempt {attempt} failed. Retrying in {delay}ms...");
            await Task.Delay(delay);
            delay *= 2;  // Exponential backoff
        }
        catch (MessageReadException) when (attempt < maxRetries)
        {
            Console.WriteLine($"Read error. Retrying in {delay}ms...");
            await Task.Delay(delay);
            delay *= 2;
        }
    }

    throw new Exception("Max retries exceeded");
}

// Usage
var design = await WithRetry(() => client.PullBeamDesignerAsync("project"));

Logging Errors

Use the optional ILogger parameter for diagnostic logging:

using Microsoft.Extensions.Logging;

var loggerFactory = LoggerFactory.Create(builder =>
{
    builder
        .AddConsole()
        .SetMinimumLevel(LogLevel.Debug);
});

var logger = loggerFactory.CreateLogger<Program>();
var client = await ErikssonBeamClient.AttemptConnection(args, logger);

See Also