Troubleshooting

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. 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.

• 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

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 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

If you use Sentry 5.7.0 in a .NET for Android application targeting net9.0-android then Sentry will have various direct dependencies. 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:

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

To resolve the problem above, you can use 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:

<PropertyGroup>
  <CentralPackageTransitivePinningEnabled
  >true</CentralPackageTransitivePinningEnabled>
</PropertyGroup>

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

<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

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

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 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

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.

See this GitHub issue for more context.

Unhandled exceptions are not captured when using an async Main method

Starting with C# 7.1, a program's Main method can be declared either synchronously or asynchronously. This is further enhanced in C# 9 by the use of 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

It's important to define what obfuscation means. If you're getting illegible stack traces because of missing debug files, all you need to do is enabling debug file upload, which is done automatically by the Sentry SDK via 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. You could create a ticket to discuss adding support to it with the maintainers.

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.

(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.

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

For more information, see the HttpClient.DefaultProxy Property.

Build Issues

Package Conflict - Conflict with Sentry.DiagnosticsSource

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

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.

Your debug window will have following messages:

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

From version 3.14.0, Sentry will respect Implicit Usings. 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:

using SentrySession = Sentry.Session;

Then SentrySession can be used instead of Sentry.Session.

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.