Add FoundryConnectionException for better network error handling in C# SDK

[Copilot]

When the Foundry Local service is unreachable, the C# SDK threw raw HttpRequestException/SocketException. Other SDKs (JS, Python, Rust) already wrap these with user-friendly messages.

Note: The CLI error message in the issue ("Exception fetching models from Azure Foundry catalog") originates from the closed-source Foundry CLI binary, not this repository.

Changes

• New FoundryConnectionException - Custom exception with clear guidance: "Could not connect to Foundry Local! Please check if the Foundry Local service is running and the host URL is correct."

• WrapHttpRequestAsync helper - Catches HttpRequestException (especially with SocketException inner) and converts to FoundryConnectionException

• Updated all HTTP operations - ListCatalogModelsAsync, GetCacheLocationAsync, ListCachedModelsAsync, DownloadModelAsync, LoadModelAsync, ListLoadedModelsAsync, UnloadModelAsync

• DownloadModelWithProgressAsync - Uses inline handling (async iterators can't use wrapper pattern), yields error result instead of throwing

Usage

try
{
    var models = await manager.ListCatalogModelsAsync();
}
catch (FoundryConnectionException ex)
{
    // Handle offline/unreachable service gracefully
    Console.WriteLine(ex.Message);
}

[!WARNING]

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• aiinfra.pkgs.visualstudio.com
  • Triggering command: /opt/hostedtoolcache/CodeQL/2.23.6/x64/codeql/csharp/tools/linux64/Semmle.Autobuild.CSharp /opt/hostedtoolcache/CodeQL/2.23.6/x64/codeql/csharp/tools/linux64/Semmle.Autobuild.CSharp (dns block)
  • Triggering command: /usr/bin/dotnet dotnet restore --no-dependencies /home/REDACTED/work/Foundry-Local/Foundry-Local/samples/cs/GettingStarted/cross-platform/FoundrySamplesXPlatform.sln --packages /home/REDACTED/work/Foundry-Local/.codeql-scratch/dbs/csharp/working/packages /p:DisableImplicitNuGetFallbackFolder=true --verbosity normal /p:TargetFrameworkRootPath=/home/REDACTED/work/Foundry-Local/.codeql-scratch/dbs/csharp/working/emptyFakeDotnetRoot /p:NetCoreTargetingPackRoot=/home/REDACTED/work/Foundry-Local/.codeql-scratch/dbs/csharp/working/emptyFakeDotnetRoot (dns block)
  • Triggering command: /usr/bin/dotnet dotnet restore --no-dependencies /home/REDACTED/work/Foundry-Local/Foundry-Local/samples/cs/GettingStarted/cross-platform/AudioTranscriptionExample/AudioTranscriptionExample.csproj --packages /home/REDACTED/work/Foundry-Local/.codeql-scratch/dbs/csharp/working/packages /p:DisableImplicitNuGetFallbackFolder=true --verbosity normal /p:TargetFrameworkRootPath=/home/REDACTED/work/Foundry-Local/.codeql-scratch/dbs/csharp/working/emptyFakeDotnetRoot /p:NetCoreTargetingPackRoot=/home/REDACTED/work/Foundry-Local/.codeql-scratch/dbs/csharp/working/emptyFakeDotnetRoot w/src/lib/compondiff w/sr w/src/lib/compon--irreversible-delete w/src/lib/compon-U0 t[bot] (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Offline] Have exception throwing (although still can be used) in no network scenario</issue_title> <issue_description>I tried to use Foundry Local on plane (i.e. no network at all). It can be used, but will always list out exception (i.e. no blocking) Both of the following situation will print out exceptions: a. Ask for Model cache list:

foundry cache list Models cached on device: Alias Model ID [07:29:29 ERR] Exception fetching models from Azure Foundry catalog $System.Net.Http.HttpRequestException: No such host is known. (ai.azure.com:443) ---> System.Net.Sockets.SocketException (11001): No such host is known. at System.Net.Sockets.Socket.AwaitableSocketAsyncEventArgs.ThrowException(SocketError, CancellationToken) + 0x40 at System.Net.Sockets.Socket.AwaitableSocketAsyncEventArgs.System.Threading.Tasks.Sources.IValueTaskSource.GetResult(Int16) + 0x58 at System.Net.Sockets.Socket.<<ConnectAsync>g__WaitForConnectWithCancellation|285_0>d.MoveNext() + 0x1b8 --- End of stack trace from previous location --- at System.Net.Http.HttpConnectionPool.<ConnectToTcpHostAsync>d__52.MoveNext() + 0x734 --- End of inner exception stack trace --- at System.Net.Http.HttpConnectionPool.<ConnectToTcpHostAsync>d__52.MoveNext() + 0x7a8 --- End of stack trace from previous location --- at System.Net.Http.HttpConnectionPool.<ConnectAsync>d__51.MoveNext() + 0x3a4 --- End of stack trace from previous location --- at System.Net.Http.HttpConnectionPool.<CreateHttp11ConnectionAsync>d__80.MoveNext() + 0x234 --- End of stack trace from previous location --- at System.Net.Http.HttpConnectionPool.<InjectNewHttp11ConnectionAsync>d__79.MoveNext() + 0x358 --- End of stack trace from previous location --- at System.Threading.Tasks.TaskCompletionSourceWithCancellation`1.<WaitWithCancellationAsync>d__1.MoveNext() + 0x100 --- End of stack trace from previous location --- at System.Net.Http.HttpConnectionPool.<SendWithVersionDetectionAndRetryAsync>d__50.MoveNext() + 0x920 --- End of stack trace from previous location --- at System.Net.Http.DiagnosticsHandler.<SendAsyncCore>d__10.MoveNext() + 0x5dc --- End of stack trace from previous location --- at System.Net.Http.RedirectHandler.<SendAsync>d__4.MoveNext() + 0x1e0 --- End of stack trace from previous location --- at System.Net.Http.HttpClient.<<SendAsync>g__Core|83_0>d.MoveNext() + 0x3f8 --- End of stack trace from previous location --- at Microsoft.Neutron.AzureFoundry.AzureFoundryApiService.<FetchModelPageFromApiAsync>d__13.MoveNext() + 0x13c --- End of stack trace from previous location --- at Microsoft.Neutron.AzureFoundry.AzureFoundryApiService.<FetchAllLocalModelsAsyncImpl>d__15.MoveNext() + 0x160 --- End of stack trace from previous location --- at Microsoft.Neutron.AzureFoundry.AzureFoundryApiService.<FetchAllLocalModelsAsync>d__14.MoveNext() + 0x7c

b. Load Model:

foundry model run qwen2.5-1.5b-instruct-qnn-npu:2 [08:25:51 ERR] Exception fetching models from Azure Foundry catalog $System.Net.Http.HttpRequestException: No such host is known. (ai.azure.com:443) ---> System.Net.Sockets.SocketException (11001): No such host is known. at System.Net.Sockets.Socket.AwaitableSocketAsyncEventArgs.ThrowException(SocketError, CancellationToken) + 0x40 at System.Net.Sockets.Socket.AwaitableSocketAsyncEventArgs.System.Threading.Tasks.Sources.IValueTaskSource.GetResult(Int16) + 0x58 at System.Net.Sockets.Socket.<<ConnectAsync>g__WaitForConnectWithCancellation|285_0>d.MoveNext() + 0x1b8 --- End of stack trace from previous location --- at System.Net.Http.HttpConnectionPool.<ConnectToTcpHostAsync>d__52.MoveNext() + 0x734 --- End of inner exception stack trace --- at System.Net.Http.HttpConnectionPool.<ConnectToTcpHostAsync>d__52.MoveNext() + 0x7a8 --- End of stack trace from previous location --- at System.Net.Http.HttpConnectionPool.<ConnectAsync>d__51.MoveNext() + 0x3a4 --- End of stack trace from previous location --- at System.Net.Http.HttpConnectionPool.<CreateHttp11ConnectionAsync>d__80.MoveNext() + 0x234 --- End of stack trace from previous location --- at System.Net.Http.HttpConnectionPool.<InjectNewHttp11ConnectionAsync>d__79.MoveNext() + 0x358 --- End of stack trace from previous location --- at System.Threading.Tasks.TaskCompletionSourceWithCancellation`1.<WaitWithCancellationAsync>d__1.MoveNext() + 0x100 --- End of stack trace from previous location --- at System.Net.Http.HttpConnectionPool.<SendWithVersionDetectionAndRetryAsync>d__50.MoveNext() + 0x920 --- End of stack trace from previous location --- at System.Net.Http.DiagnosticsHandler.<SendAsyncCore>d__10.MoveNext() + 0x5dc --- End of stack trace from previous location --- at System.Net.Http.RedirectHandler.<SendAsync>d__4.MoveNext() + 0x1e0 --- End of stack trace from previous location --- at System.N...

• Fixes microsoft/Foundry-Local#341

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[vercel[bot]]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
foundry-local	Ready	Preview	Comment	Dec 4, 2025 0:14am