Errors & Debugging

C# problems arrive at two very different moments. A compile error is the compiler (Roslyn) refusing to build your program: the syntax is wrong, a name does not exist, or the types do not fit. Nothing runs at all. A runtime exception happens while the program is running: the code was valid, but the data was not what you expected — a null, a missing key, text that is not a number. Knowing which one you are looking at tells you where to look.

Anatomy of a compiler error

Program.cs(6,19): error CS0103: The name 'grade' does not exist in the current context
Program.cs(4,12): warning CS0219: The variable 'grade' is assigned but its value is never used

The build failed. Fix the build errors and run again.

File, (line,column), severity, the CS code, the message. Warnings do not stop the build; errors do.

• Fix the first error first. One missing brace can produce twenty follow-on errors that vanish once it is fixed.
• Search the code. Every CS number has a page on Microsoft Learn with examples — searching "CS0266" is faster than searching the message.
• Read warnings too. The warning above is a clue to the error: the variable exists, just not where it is used.

Reading a .NET stack trace

This program calls PlaceOrder, which calls UnitPrice, which calls Divide. The second quantity is 0, and here is what .NET printed:

PlaceOrder(new[] { 2, 0, 1 });

static void PlaceOrder(int[] quantities)
{
    foreach (int q in quantities)
        Console.WriteLine(UnitPrice(100, q));
}

static int UnitPrice(int total, int qty)
{
    return Divide(total, qty);
}

static int Divide(int a, int b) => a / b;

50
Unhandled exception. System.DivideByZeroException: Attempted to divide by zero.
   at Program.<<Main>$>g__Divide|0_2(Int32 a, Int32 b) in Program.cs:line 14
   at Program.<<Main>$>g__UnitPrice|0_1(Int32 total, Int32 qty) in Program.cs:line 11
   at Program.<<Main>$>g__PlaceOrder|0_0(Int32[] quantities) in Program.cs:line 6
   at Program.<Main>$(String[] args) in Program.cs:line 1

Real output. The first line printed (50) shows the first order worked; the crash came on the second.

1. 1
   1. First line: what went wrong

   The exception type and message: DivideByZeroException: Attempted to divide by zero.

2. 2
   2. Bottom line: where the story starts

   <Main>$ is your top-level statements, line 1. Reading upwards gives the chain of calls that led to the crash: Main → PlaceOrder → UnitPrice → Divide.

3. 3
   3. Top "at" line: where it was thrown

   Line 14, inside Divide. Names like <<Main>$>g__Divide|0_2 are how the compiler names local functions; read them as "Divide".

4. 4
   4. Find the first frame that is YOUR mistake

   Divide did what it was told. The real question is why qty was 0 — so the fix probably belongs in UnitPrice or PlaceOrder, not in Divide.

5. 5
   5. Inner exceptions

   A line starting ---> introduces an inner exception: the original cause that was wrapped by another. The innermost one is usually the one to fix.

You can also catch an exception and inspect it in code: its type, Message, and InnerException. This is what logging frameworks do for you.

try
{
    LoadConfig("port=abc");
}
catch (Exception ex)
{
    Console.WriteLine($"{ex.GetType().Name}: {ex.Message}");
    Console.WriteLine($"caused by {ex.InnerException?.GetType().Name}: {ex.InnerException?.Message}");
}

static int LoadConfig(string line)
{
    string value = line.Split('=')[1];
    try
    {
        return int.Parse(value);
    }
    catch (FormatException fe)
    {
        throw new InvalidOperationException($"bad config line '{line}'", fe);   // keep the cause
    }
}

InvalidOperationException: bad config line 'port=abc'
caused by FormatException: The input string 'abc' was not in a correct format.

These five come from the compiler not being able to find something — a variable, a type, a member, or the end of a statement.

int score = 72;
if (score >= 50)
{
    string grade = "pass";
}
Console.WriteLine(grade);

Program.cs(6,19): error CS0103: The name 'grade' does not exist in the current context
Program.cs(4,12): warning CS0219: The variable 'grade' is assigned but its value is never used

int score = 72;
string grade = "fail";
if (score >= 50)
{
    grade = "pass";
}
Console.WriteLine(grade);

var sb = new StringBuilder();
sb.Append("hello");
Console.WriteLine(sb);

Program.cs(1,14): error CS0246: The type or namespace name 'StringBuilder' could not be found (are you missing a using directive or an assembly reference?)

using System.Text;

var sb = new StringBuilder();
sb.Append("hello");
Console.WriteLine(sb);

Console.WriteLine("Hello")
Console.WriteLine("World");

Program.cs(1,27): error CS1002: ; expected

Console.WriteLine("Hello");
Console.WriteLine("World");

string word = "handbook";
Console.WriteLine(word.Lenght);

Program.cs(2,24): error CS1061: 'string' does not contain a definition for 'Lenght' and no accessible extension method 'Lenght' accepting a first argument of type 'string' could be found (are you missing a using directive or an assembly reference?)

string word = "handbook";
Console.WriteLine(word.Length);

Counter.Increment();

class Counter
{
    private int count;
    public void Increment() => count++;
}

Program.cs(1,1): error CS0120: An object reference is required for the non-static field, method, or property 'Counter.Increment()'

var counter = new Counter();
counter.Increment();
counter.Increment();
Console.WriteLine(counter.Count);

class Counter
{
    public int Count { get; private set; }
    public void Increment() => Count++;
}

C# is statically typed: every expression has a type the compiler knows, and it refuses conversions that could lose data or make no sense. It also tracks whether every variable definitely has a value and whether every path through a method returns one.

Console.Write("Age: ");
int age = Console.ReadLine();
Console.WriteLine(age + 1);

Program.cs(2,11): error CS0029: Cannot implicitly convert type 'string' to 'int'

Console.Write("Age: ");
if (int.TryParse(Console.ReadLine(), out int age))
    Console.WriteLine(age + 1);
else
    Console.WriteLine("please type a whole number");

int[] marks = { 70, 85, 90 };
int average = marks.Sum() / 3.0;
Console.WriteLine(average);

Program.cs(2,15): error CS0266: Cannot implicitly convert type 'double' to 'int'. An explicit conversion exists (are you missing a cast?)

int[] marks = { 70, 85, 90 };
double average = marks.Sum() / 3.0;
int rounded = (int)Math.Round(average);
Console.WriteLine(rounded);

string input = "5";
if (input == 5)
    Console.WriteLine("five");

Program.cs(2,5): error CS0019: Operator '==' cannot be applied to operands of type 'string' and 'int'

string input = "5";
if (int.TryParse(input, out int n) && n == 5)
    Console.WriteLine("five");

int discount;
bool member = true;
if (member)
    discount = 10;
Console.WriteLine(discount);

Program.cs(5,19): error CS0165: Use of unassigned local variable 'discount'

int discount = 0;
bool member = true;
if (member)
    discount = 10;
Console.WriteLine(discount);

Console.WriteLine(Grade(72));

static string Grade(int score)
{
    if (score >= 90) return "A";
    else if (score >= 50) return "Pass";
}

Program.cs(3,15): error CS0161: 'Grade(int)': not all code paths return a value

Console.WriteLine(Grade(72));

static string Grade(int score)
{
    if (score >= 90) return "A";
    else if (score >= 50) return "Pass";
    else return "Fail";
}

These programs all compile. They crash only when the bad line runs with the bad data. Each shows the real Unhandled exception output from .NET 10.

var order = new Order { Id = 7 };
Console.WriteLine(order.Customer.Name.ToUpper());

class Customer { public string Name { get; set; } = ""; }
class Order
{
    public int Id { get; set; }
    public Customer? Customer { get; set; }
}

Program.cs(2,19): warning CS8602: Dereference of a possibly null reference.
Unhandled exception. System.NullReferenceException: Object reference not set to an instance of an object.
   at Program.<Main>$(String[] args) in Program.cs:line 2

var order = new Order { Id = 7 };
Console.WriteLine(order.Customer?.Name.ToUpper() ?? "(guest)");

class Customer { public string Name { get; set; } = ""; }
class Order
{
    public int Id { get; set; }
    public Customer? Customer { get; set; }
}

string path = args[0];
Console.WriteLine($"reading {path}");

Unhandled exception. System.IndexOutOfRangeException: Index was outside the bounds of the array.
   at Program.<Main>$(String[] args) in Program.cs:line 1

if (args.Length == 0)
{
    Console.WriteLine("usage: dotnet run -- <path>");
    return;
}
string path = args[0];
Console.WriteLine($"reading {path}");

object boxed = "42";
int n = (int)boxed;
Console.WriteLine(n + 1);

Unhandled exception. System.InvalidCastException: Unable to cast object of type 'System.String' to type 'System.Int32'.
   at Program.<Main>$(String[] args) in Program.cs:line 2

object boxed = "42";
int n = boxed switch
{
    int i => i,
    string s when int.TryParse(s, out int parsed) => parsed,
    _ => 0,
};
Console.WriteLine(n + 1);

var prices = new Dictionary<string, decimal>
{
    ["apple"] = 0.5m,
    ["bread"] = 2.25m,
};
Console.WriteLine(prices["milk"]);

Unhandled exception. System.Collections.Generic.KeyNotFoundException: The given key 'milk' was not present in the dictionary.
   at System.Collections.Generic.Dictionary`2.get_Item(TKey key)
   at Program.<Main>$(String[] args) in Program.cs:line 6

var prices = new Dictionary<string, decimal>
{
    ["apple"] = 0.5m,
    ["bread"] = 2.25m,
};
if (prices.TryGetValue("milk", out decimal price))
    Console.WriteLine(price);
else
    Console.WriteLine("milk is not on the price list");

string raw = "1,500";
int amount = int.Parse(raw);
Console.WriteLine(amount * 2);

Unhandled exception. System.FormatException: The input string '1,500' was not in a correct format.
   at System.Number.ThrowFormatException[TChar](ReadOnlySpan`1 value)
   at System.Int32.Parse(String s)
   at Program.<Main>$(String[] args) in Program.cs:line 2

using System.Globalization;

string raw = "1,500";
if (int.TryParse(raw, NumberStyles.AllowThousands, CultureInfo.InvariantCulture, out int amount))
    Console.WriteLine(amount * 2);
else
    Console.WriteLine($"not a number: {raw}");

NullReferenceException is the most common .NET crash, so modern C# gives you a tool against it: nullable reference types, on by default in new projects (<Nullable>enable</Nullable>) and in file-based apps. With it on, string means "never null" and string? means "might be null", and the compiler tracks which is which through your code. These are warnings, so the program still builds — which is exactly why people ignore them. Do not.

string email = FindEmail(2);
Console.WriteLine(email.Length);

static string? FindEmail(int id) => id == 1 ? "[email protected]" : null;

Program.cs(1,16): warning CS8600: Converting null literal or possible null value to non-nullable type.
Program.cs(2,19): warning CS8602: Dereference of a possibly null reference.

Real dotnet build output. Both warnings point at the crash that line 2 would cause at runtime.

string? email = FindEmail(2);

// 1. check, and the compiler knows it is not null inside the if
if (email is not null)
    Console.WriteLine(email.Length);

// 2. ?. returns null instead of throwing, ?? supplies a fallback
int length = email?.Length ?? 0;
Console.WriteLine(length);

// 3. fail fast with a clear message at the boundary
string required = FindEmail(1) ?? throw new InvalidOperationException("user 1 has no email");
Console.WriteLine(required);

static string? FindEmail(int id) => id == 1 ? "[email protected]" : null;

0
[email protected]

<PropertyGroup>
  <Nullable>enable</Nullable>
  <!-- make the null warnings (and all others) fail the build -->
  <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  <!-- or only some of them -->
  <WarningsAsErrors>nullable</WarningsAsErrors>
</PropertyGroup>

Teams that turn warnings into errors stop NullReferenceException bugs at code review instead of in production.

Reading the error gets you to a line. When the line looks right and the result is still wrong, you need to watch the program run. The debugger is the fastest way; it is built into Visual Studio and Rider, and into VS Code with the C# Dev Kit extension.

1. 1
   Set a breakpoint

   Click the margin next to a line (F9). Start with debugging (F5); execution pauses before that line runs.

2. 2
   Look at the state

   Hover over variables, or use the Locals and Watch windows. Add an expression such as orders.Count(o => o.Total > 100) to Watch to evaluate it live.

3. 3
   Step

   Step Over (F10) runs the line; Step Into (F11) goes into the method it calls; Step Out (Shift+F11) finishes the current method. The Call Stack window is the stack trace, live.

4. 4
   Conditional breakpoints

   Right-click a breakpoint and add a condition (i == 997) or a hit count, so a loop stops only on the iteration that goes wrong.

5. 5
   Break on exceptions

   In the Exception Settings, tick an exception type (e.g. NullReferenceException) to stop the moment it is thrown, with every variable still in view — even if something later catches it.

Debug.WriteLine versus Console.WriteLine

Console.WriteLine goes to the program's output, which your users see. System.Diagnostics.Debug.WriteLine goes to attached trace listeners — the debugger's Output window — and calls to it are removed entirely from Release builds. So it is safe to leave in, but it prints nothing to the console:

using System.Diagnostics;

int[] cart = { 250, 120, 80 };
int total = 0;
foreach (int price in cart)
{
    total += price;
    Debug.WriteLine($"added {price}, running total {total}");   // Output window only
}
Console.WriteLine($"Total: {total}");

Total: 450

Logging for code you cannot attach a debugger to

In production there is no debugger. Real .NET apps log through ILogger<T> from Microsoft.Extensions.Logging, which ASP.NET Core wires up for you. Use message templates with named placeholders rather than string interpolation: the values are stored as fields, so a log system can search for every line where OrderId is 42.

public class OrderService(ILogger<OrderService> logger, AppDb db)
{
    public async Task<Order?> GetAsync(int orderId)
    {
        logger.LogInformation("Loading order {OrderId}", orderId);
        var order = await db.Orders.FindAsync(orderId);
        if (order is null)
            logger.LogWarning("Order {OrderId} not found", orderId);
        return order;
    }

    public async Task CancelAsync(int orderId)
    {
        try { /* ... */ }
        catch (Exception ex)
        {
            // pass the exception object: the log keeps type, message AND stack trace
            logger.LogError(ex, "Cancelling order {OrderId} failed", orderId);
            throw;   // rethrow with the original stack trace (not "throw ex;")
        }
    }
}

Compile error

A problem Roslyn finds while building (CSxxxx); the program does not run at all.

Warning

A diagnostic that does not stop the build but usually points at a real bug (e.g. CS8602).

Runtime exception

An error object thrown while the program runs; unhandled, it ends the process with a stack trace.

Stack trace

The chain of method calls active when an exception was thrown: throw site at the top, Main at the bottom.

Inner exception

The original exception wrapped inside another one, shown after --->.

Nullable reference types

The compiler feature that tracks string versus string? and warns before a null can be dereferenced.

Breakpoint

A marker that pauses execution in the debugger before a line runs.

Structured logging

Logging with named placeholders so each value is stored as a searchable field.