An unhandled error has occurred 🟪 .NET

Blazor: An unhandled error has occurred. Reload 🗙

A Blazor component threw an exception; Blazor Server tears down the circuit (or WebAssembly logs to the console) and shows the reload bar.

Seen on: .NET

Meaning

Look in the browser console (WASM) or server logs (Server) for the real exception. Enable detailed errors in development. Use ErrorBoundary to contain failures in parts of the UI.

Common causes

  • Exception in component lifecycle (OnInitializedAsync)
  • Null data rendered before load completes
  • JS interop errors
  • Disconnected circuit on Blazor Server

⚡ Quick fix

  1. Check console/server logs
  2. Enable DetailedErrors in development
  3. Wrap risky components in <ErrorBoundary>

Detailed fix by platform

C#

  1. builder.Services.AddServerSideBlazor().AddCircuitOptions(o => o.DetailedErrors = builder.Environment.IsDevelopment());

Razor

  1. csharp
    <ErrorBoundary>
  <ChildContent><OrdersGrid /></ChildContent>
  <ErrorContent>Something went wrong loading orders.</ErrorContent>
</ErrorBoundary>

How to diagnose

  1. Logs — Exception and component
  2. Data — Null before loaded?
  3. Interop — JS errors?

🔧 Still not fixed?

Many errors look alike. If the steps above didn’t solve it, one of these is probably what you’re facing:

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.