# Troubleshooting

## Learn more about how to troubleshoot common issues with the .NET SDK.

## [Sentry CLI not configured](#sentry-cli-not-configured)

The following message may appear in your build output:

> The Sentry CLI is not fully configured with authentication, organization, and project.

The message currently appears as information only, though we may change it to a warning in the future. This means that you are building in `Release` configuration, and you have not fully configured [MSBuild for Sentry CLI](../configuration/msbuild/). You can handle this in one of the following ways:

* You can enable the Sentry CLI in your build by providing configuration details, as described in [the documentation here](../configuration/msbuild/).

* You can prevent the message from being generated by setting the property `<UseSentryCLI>false</UseSentryCLI>` in your .NET project file, or with `/p:UseSentryCLI=false` on the command line to `dotnet build` or `msbuild`. Sentry CLI will be disabled.

* You can do nothing, and just ignore the message. Sentry CLI will be disabled.

Keep in mind that if the Sentry CLI is disabled, then debug information files such as PDB symbols will not be sent to Sentry. If Sentry cannot locate symbols, then it cannot perform symbolication of stack traces. This means that for some types of projects (depending on configuration), you may not see filenames and line numbers to help you locate the source of an exception.

## [Detected package version outside of dependency constraint](#detected-package-version-outside-of-dependency-constraint)

In .NET for Android applications the Sentry SDK needs to make use of a limited number of Android APIs that form part of the operating system. Implicitly, Sentry depends on [various Java packages](https://github.com/getsentry/sentry-dotnet/blob/ebc1115d6c928ff56244afa3a1ce1d79b078fbf4/src/Sentry.Bindings.Android/Sentry.Bindings.Android.csproj#L45-L56) then.

If you are using third party libraries that depend on different versions of these same Java packages, you may see `NU1605`, `NU1608` and/or `NU1107` warnings when trying to run `dotnet restore`.

Sentry itself only specifies a minimum version of the Java packages that it depends on, so is compatible with any higher versions of the same Java packages. However, these Java packages come with their own dependencies, which are therefore transitive dependencies for Sentry. The transitive dependencies of the Sentry SDK can sometimes be incompatible with the transitive dependencies of other third party libraries and NuGet isn't smart enough to resolve those conflicts without a bit of guidance.

Such problems need to be resolved on a case by case basis but the following example should demonstrate how you can resolve these issues if you run into them in your own application.

### [Example Problem](#example-problem)

If you use `Sentry` `5.7.0` in a .NET for Android application targeting `net9.0-android` then Sentry will have various [direct dependencies](https://www.nuget.org/packages/Sentry/5.7.0#dependencies-body-tab). However those direct dependencies come with their own dependencies, which for Sentry are transitive dependencies.

If you also use `Microsoft.Maui.Essentials` version `9.0.50`, ultimately it depends on conflicting version of those same transitive dependencies.

In this scenario you would see a warning or an error like the following when running `dotnet restore`:

```bash
NU1608: Detected package version outside of dependency constraint: Xamarin.AndroidX.Lifecycle.Common.Java8 2.8.5.1 requires Xamarin.AndroidX.Lifecycle.Common (>= 2.8.5.1 && < 2.8.6) but version Xamarin.AndroidX.Lifecycle.Common 2.8.7.2 was resolved.
```

### [Example Solution](#example-solution)

To resolve the problem above, you can use [Transitive Pinning](https://learn.microsoft.com/en-us/nuget/consume-packages/central-package-management#transitive-pinning) to resolve explicit versions of transitive dependencies (rather than letting NuGet resolve these automatically).

To enable Transitive Pinning, add the following to your `csproj` or `Directory.Build.props` file:

```xml
<PropertyGroup>
  <CentralPackageTransitivePinningEnabled
  >true</CentralPackageTransitivePinningEnabled>
</PropertyGroup>
```

You can then pin the appropriate versions of the transitive dependency that's causing you problems:

```xml
<ItemGroup>
    <PackageReference
    Include="Xamarin.AndroidX.Lifecycle.Common.Java8"
    Version="2.8.7.2"
  />
</ItemGroup>
```

Although the Sentry SDK only needs `Xamarin.AndroidX.Lifecycle.Common.Java8 2.8.5.1`, that version is problematic since it locks the transitive dependency `Xamarin.AndroidX.Lifecycle.Common` into the range `(>= 2.8.5.1 && < 2.8.6)`. By explicitly pinning `Xamarin.AndroidX.Lifecycle.Common.Java8` to `2.8.7.2` to match the version used by `Microsoft.Maui.Essentials`, we can resolve the conflict.

## [Updating to 4.12.0 broke my .NET iOS App](#updating-to-4120-broke-my-net-ios-app)

Support for Xcode 16.0 was added on version 4.12.0 of the Sentry SDK for .NET If you are using Xcode 16.0, you will need to update the SDK version 4.12.0 or later. If you are still using Xcode 15.4 or earlier, you need to continue to use version 4.11.0 or earlier.

Using Xcode 16 to build .NET applications targeting iOS and Mac Catalyst requires .NET workload for iOS SDK version 18.0.8303. We built the SDK version 4.12.0 using Xcode 16 in order to support this scenario. That, unfortunately, breaks folks using older version of Xcode.

As such, if you are using SDK version 4.12.x and targeting iOS or Mac Catalyst, you will need to install and use Xcode 16 and workload iOS SDK 18.0.8303

Note that .NET 9 will also support Xcode 16, when it is released next month (Nov 2024).

## [The event is dropped by Sentry because it's too large](#the-event-is-dropped-by-sentry-because-its-too-large)

> Sentry: (Error) Sentry rejected the envelope 5bfe4129cb2446c08768b16479865035. Status code: RequestEntityTooLarge. Error detail: failed to read request body. Error causes: A payload reached size limit..

You can have the [Sentry .NET SDK write these envelopes to a path](https://github.com/getsentry/sentry-dotnet/blob/e62013ca63436d2a786fb229570e96f42c7c4044/src/Sentry/Http/HttpTransportBase.cs#L341-L363) in order to troubleshoot why they are too large. Set the environment variable `SENTRY_KEEP_LARGE_ENVELOPE_PATH` to the directory you want these to be written to. Make sure the process the SDK is running in has write access to it.

## [User IP address in Sentry shows up as the server IP](#user-ip-address-in-sentry-shows-up-as-the-server-ip)

If you're using a proxy server that relies on `X-Forwarded-For`, you might need to [configure ASP.NET Core so that it's aware of it](https://docs.microsoft.com/aspnet/core/host-and-deploy/proxy-load-balancer).

See [this GitHub issue](https://github.com/getsentry/sentry-dotnet/issues/258) for more context.

## [Unhandled exceptions are not captured when using an async `Main` method](#unhandled-exceptions-are-not-captured-when-using-an-async-main-method)

Starting with C# 7.1, a program's [`Main` method](https://docs.microsoft.com/dotnet/csharp/fundamentals/program-structure/main-command-line) can be declared either synchronously or asynchronously. This is further enhanced in C# 9 by the use of [top-level statements](https://learn.microsoft.com/dotnet/csharp/fundamentals/program-structure/top-level-statements), which can also be declared synchronously or asynchronously.

While using either of these features with previous versions of the Sentry .NET SDK, when `SentrySdk.Init` is called within a `using` statement unhandled exceptions might not get captured. Additionally, if you were using an async main, associated transactions might not get marked as failed and sent to Sentry.

These issues have been fully resolved as of version 3.31.0 of the Sentry .NET SDK. To safely use an async main, update your version to the newest release. It's no longer required to dispose of the result of calling `SentrySdk.Init`.

## [Obfuscated Code and Stack Traces](#obfuscated-code-and-stack-traces)

It's important to define what obfuscation means. If you're getting illegible stack traces because of missing [debug files](/platforms/dotnet/data-management/debug-files/), all you need to do is enabling debug file upload, which is done automatically by the [Sentry SDK via MSBuild](/platforms/dotnet/guides/aspnet/configuration/msbuild/).

Some custom tools obfuscate .NET Intermediate Language (IL) in order to make apps harder to reverse-engineer; Sentry does not currently support these tools. This is because each obfuscator uses its own custom logic when dealing with deobfuscation, making it impractical to implement universal support.

If you're working with obfuscated code, you have several options:

1. **Use a proxy service**: You can route exceptions through your own web service proxy where you can deobfuscate the stack traces before sending them to Sentry. This gives you full control over the deobfuscation process.

2. **Preserve method names**: Many obfuscation tools allow you to disable method name obfuscation while still obfuscating the code inside methods. This approach results in more readable stack traces while maintaining code protection. Configure your obfuscator to preserve method names if this balance of readability and security meets your needs.

3. **Contribute to Symbolic**: [Our symbolication library is open source](https://github.com/getsentry/symbolic). You could create a ticket to discuss adding support to it with the maintainers.

## [Proxy Server](#proxy-server)

Often, your server can only access the internet through a proxy server. If that's the case, make sure your proxy server is configured so the `HttpClient` used by Sentry's SDK can pick it up.

```csharp
(SentryOptions options) =>
{
    // Read the proxy's address from, for example, your Configuration
    options.HttpProxy = new WebProxy(new Uri("http://proxyserver:80/"));
};
```

Alternatively, you may configure the default proxy that all `HttpClient` instances use if no proxy is set explicitly.

```csharp
System.Net.Http.HttpClient.DefaultProxy = new WebProxy(new Uri("http://proxyserver:80/"));
```

For more information, see the [HttpClient.DefaultProxy Property](https://learn.microsoft.com/dotnet/api/system.net.http.httpclient.defaultproxy).

## [Build Issues](#build-issues)

### [Package Conflict - `Conflict with Sentry.DiagnosticsSource`](#package-conflict---conflict-with-sentrydiagnosticssource)

```bash
The call is ambiguous between the following methods or properties:
Sentry.SentryOptionsExtensions.DisableDiagnosticSourceIntegration(Sentry.SentryOptions)
and Sentry.SentryOptionsDiagnosticExtensions.DisableDiagnosticSourceIntegration(Sentry.SentryOptions)
```

The above error means that the version of the Sentry package you are using already contains the `DiagnosticSource` integration within itself, but you additionally installed `Sentry.DiagnosticSource`, which is only relevant for older framework versions.

To resolve this problem, remove the package reference to `Sentry.DiagnosticSource`.

### [Missing Definition](#missing-definition)

`SentryOptions does not contain a definition for AddDiagnosticSourceIntegration.`

The above error could have two meanings:

* You're using an outdated SDK (3.8.3 or older).

* Your project already includes the integration automatically. You can validate it by observing the debug information from Sentry SDK. [Enable it through the options.](/platforms/dotnet/configuration/options/#debug)

Your debug window will have following messages:

```bash
Debug: Logging enabled with ConsoleDiagnosticLogger and min level: Debug
Debug: Initializing Hub for Dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0'.
Debug: Using 'GzipBufferedRequestBodyHandler' body compression strategy with level Optimal.
Debug: New scope pushed.
Debug: Registering integration: 'AutoSessionTrackingIntegration'.
Debug: Registering integration: 'AppDomainUnhandledExceptionIntegration'.
Debug: Registering integration: 'AppDomainProcessExitIntegration'.
Debug: Registering integration: 'TaskUnobservedTaskExceptionIntegration'.
Debug: Registering integration: 'SentryDiagnosticListenerIntegration'.
```

If the debug file contains information about `SentryDiagnosticListenerIntegration`, then your project already includes the integration automatically.

### [Implicit Usings](#implicit-usings)

From version 3.14.0, Sentry will respect [Implicit Usings](https://docs.microsoft.com/en-us/dotnet/core/project-sdk/overview#implicit-using-directives). This means is Implicit Usings is enabled (`<ImplicitUsings>enable</ImplicitUsings>` or `<ImplicitUsings>true</ImplicitUsings>`) then `Sentry` will be added to the current global using directives. This means that `using Sentry;` can be omitted from any `.cs` files.

In some scenarios Implicit Usings can result in type name conflicts. For example `Session` may exist in multiple namespaces. This can be resolved by fully qualifying the type inline (`Sentry.Session`), or with a [using alias](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/using-directive#using-alias):

```bash
using SentrySession = Sentry.Session;
```

Then `SentrySession` can be used instead of `Sentry.Session`.

### [Visual Studio Hot Restart Incompatibility](#visual-studio-hot-restart-incompatibility)

Attempting to build a .NET MAUI iOS app will result in an error if you use Visual Studio Hot Restart when developing on Windows with a remote Mac:

> The xcframework sentry.bindings.cocoa\5.0.1\lib\net8.0-ios17.0\Sentry.Bindings.Cocoa.resources.zip has an incorrect or unknown format and cannot be processed.

This happens because Hot Restart does not support static iOS libraries or frameworks containing static libraries, as detailed in the [Microsoft documentation](https://learn.microsoft.com/en-us/dotnet/maui/ios/hot-restart?view=net-maui-9.0#limitations).
