C# try catch: Handling Exceptions with catch, when and finally

When something goes wrong at run time (a file is missing, text is not a number, a key is not in a dictionary), .NET throws an exception: an object describing the error. The exception travels up the call stack until a catch block handles it. If nothing does, the program stops and prints the error.

A basic try catch

Wrap the code that can fail in try, and handle the failure in catch:

using System;

class Program
{
    static void Main()
    {
        string[] inputs = { "42", "forty-two", "7" };

        foreach (string input in inputs)
        {
            try
            {
                int n = int.Parse(input);
                Console.WriteLine(input + " doubled is " + (n * 2));
            }
            catch (FormatException)
            {
                Console.WriteLine("'" + input + "' is not a number");
            }
        }
        Console.WriteLine("Still running");
    }
}

Output:

42 doubled is 84
'forty-two' is not a number
7 doubled is 14
Still running

When int.Parse("forty-two") throws, the Console.WriteLine after it in the try block is skipped, the catch (FormatException) block runs, and the loop continues. You can leave out the variable (catch (FormatException)) when you do not need the exception object.

This particular case has a better tool: int.TryParse(input, out int n) returns false instead of throwing. Exceptions are for situations the code does not expect; input that is often invalid is expected, so check it instead of catching.

How an exception travels

An exception thrown deep inside a call chain unwinds every method until it finds a matching handler. Code after the throw in each of those methods does not run.

using System;
using System.Collections.Generic;

class Program
{
    static Dictionary<string, decimal> prices = new Dictionary<string, decimal>
    {
        ["tea"] = 2.50m,
    };

    static decimal PriceOf(string item)
    {
        return prices[item];                         // throws for a missing item
    }

    static decimal OrderTotal(string item, int qty)
    {
        decimal total = PriceOf(item) * qty;
        Console.WriteLine("OrderTotal finished");    // skipped when PriceOf throws
        return total;
    }

    static void Main()
    {
        try
        {
            Console.WriteLine(OrderTotal("tea", 2));
            Console.WriteLine(OrderTotal("cake", 1));
            Console.WriteLine("not reached");
        }
        catch (KeyNotFoundException e)
        {
            Console.WriteLine("Caught " + e.GetType().Name + " in Main");
        }
    }
}

Output:

OrderTotal finished
5.00
Caught KeyNotFoundException in Main

PriceOf and OrderTotal have no catch, so the exception passes straight through them to Main. Put a handler at the level that knows what to do about the failure, which is often not where it happened.

Catching specific exceptions, in the right order

A catch clause handles its type and every type derived from it. When there are several clauses, the first one that matches wins, so order them from most specific to most general:

using System;

class Program
{
    static void Divide(string a, string b)
    {
        try
        {
            int x = int.Parse(a);
            int y = int.Parse(b);
            Console.WriteLine(a + " / " + b + " = " + (x / y));
        }
        catch (DivideByZeroException)
        {
            Console.WriteLine("Cannot divide by zero");
        }
        catch (FormatException)
        {
            Console.WriteLine("Both values must be whole numbers");
        }
        catch (Exception e)
        {
            Console.WriteLine("Unexpected: " + e.GetType().Name);
        }
    }

    static void Main()
    {
        Divide("10", "2");
        Divide("10", "0");
        Divide("ten", "2");
        Divide("99999999999", "1"); // too large for int
    }
}

Output:

10 / 2 = 5
Cannot divide by zero
Both values must be whole numbers
Unexpected: OverflowException

The last call throws OverflowException, which neither specific clause handles, so the general catch (Exception e) does. Putting catch (Exception) first would make the clauses after it unreachable, and the compiler rejects that with error CS0160.

Exception filters with when

C# 6 added when: a condition that decides whether a catch clause applies. If it is false, the runtime carries on looking for another handler as if the clause did not exist.

using System;

class ApiException : Exception
{
    public int StatusCode { get; }
    public ApiException(int statusCode) : base("HTTP " + statusCode)
    {
        StatusCode = statusCode;
    }
}

class Program
{
    static void Call(int status)
    {
        try
        {
            throw new ApiException(status);
        }
        catch (ApiException e) when (e.StatusCode == 404)
        {
            Console.WriteLine("Not found: show an empty page");
        }
        catch (ApiException e) when (e.StatusCode >= 500)
        {
            Console.WriteLine("Server error " + e.StatusCode + ": retry later");
        }
        catch (Exception e) when (e is ArgumentException || e is FormatException)
        {
            Console.WriteLine("Bad input");
        }
    }

    static void Main()
    {
        Call(404);
        Call(503);
        try
        {
            Call(401); // no clause matches: it propagates
        }
        catch (ApiException e)
        {
            Console.WriteLine("Unhandled by Call: " + e.Message);
        }
    }
}

Output:

Not found: show an empty page
Server error 503: retry later
Unhandled by Call: HTTP 401

Filters let you branch on data inside the exception without catching and rethrowing. They are also the clean way to handle two unrelated types identically, as the third clause does. A filter runs before the stack is unwound, so a debugger or crash dump still shows the original state when no filter matches.

finally: code that always runs

A finally block runs when control leaves the try, whether it finished, returned early, or threw. It is where cleanup goes. (One caveat: if nothing anywhere catches the exception, the process can end without running it.)

using System;

class Program
{
    static string Process(int step)
    {
        Console.WriteLine("Open connection");
        try
        {
            if (step == 1) return "returned early";
            if (step == 2) throw new InvalidOperationException();
            return "finished";
        }
        catch (InvalidOperationException)
        {
            return "handled error";
        }
        finally
        {
            Console.WriteLine("Close connection");
        }
    }

    static void Main()
    {
        Console.WriteLine(Process(0));
        Console.WriteLine(Process(1));
        Console.WriteLine(Process(2));
    }
}

Output:

Open connection
Close connection
finished
Open connection
Close connection
returned early
Open connection
Close connection
handled error

In every case "Close connection" prints before the method's result reaches Main: the finally runs after the return value is computed but before the method actually returns. A try can have a finally with no catch at all, which cleans up while letting the exception continue to the caller.

For objects that implement IDisposable (files, streams, connections), the using statement writes this try/finally for you.

Rethrowing: throw; vs throw e;

Sometimes a catch block logs or records something and then lets the exception continue. How you rethrow decides whether the stack trace survives:

using System;
using System.Runtime.CompilerServices;

class Program
{
    // NoInlining keeps this small method as its own frame in the stack trace.
    [MethodImpl(MethodImplOptions.NoInlining)]
    static void LoadConfig()
    {
        throw new InvalidOperationException("config file missing");
    }

    static void RethrowKeep()
    {
        try { LoadConfig(); }
        catch (InvalidOperationException) { throw; }      // original trace
    }

    static void RethrowReset()
    {
        try { LoadConfig(); }
        catch (InvalidOperationException e) { throw e; }  // trace restarts here
    }

    static void Main()
    {
        try { RethrowKeep(); }
        catch (Exception e)
        {
            Console.WriteLine("throw;   trace mentions LoadConfig: " + e.StackTrace.Contains("LoadConfig"));
        }

        try { RethrowReset(); }
        catch (Exception e)
        {
            Console.WriteLine("throw e; trace mentions LoadConfig: " + e.StackTrace.Contains("LoadConfig"));
        }
    }
}

Output:

throw;   trace mentions LoadConfig: True
throw e; trace mentions LoadConfig: False

throw e; treats the exception as newly thrown from the catch block, so the frames below it, including the method where the error happened, are gone from the trace. Always rethrow with a bare throw;. (The NoInlining attribute is only there because the JIT may merge a method this small into its caller, which would hide it from both traces.)

To add context instead, wrap the exception in a new one and pass the original as the inner exception: throw new ConfigException("Could not start the app", e);. The inner exception keeps its own stack trace, and loggers print the chain. Writing your own exception types is covered in throwing exceptions.

The Exception object

Every exception derives from System.Exception. The members you use most:

Log e.ToString() rather than e.Message when you want to diagnose a failure later: the message alone rarely says where the problem was. Do not show e.ToString() to end users.

Common exception types

NullReferenceException, IndexOutOfRangeException and InvalidCastException almost always mean a bug. Fix the code rather than catching them.

Not swallowing exceptions

An empty catch hides every error, including the ones you did not anticipate:

try
{
    SaveOrder(order);
}
catch (Exception)
{
    // nothing: the order silently was not saved
}

The program keeps running as if the save worked, and the real cause is lost. Guidelines that keep exception handling honest:

• Catch only what you can handle, at the level that can handle it.
• If you catch to log, rethrow with throw; unless the program can really continue.
• Catch Exception only at the outer edge: Main, a request handler, a worker loop.
• Prefer TryParse, TryGetValue and null checks over exceptions for expected cases. Throwing is slow compared to a check, while a try block that throws nothing costs almost nothing.

Common mistakes

• catch (Exception) first. Later clauses become unreachable (CS0160).
• throw e; to rethrow. It erases the original stack trace; use throw;.
• Empty catch blocks. Errors vanish; at least log and rethrow.
• Using exceptions for control flow. Validate input with TryParse instead of catching FormatException.
• Showing e.Message of a framework exception to users. The wording differs between .NET versions and is written for developers.