diff --git a/docs/setup-asp-dot-net.asciidoc b/docs/setup-asp-dot-net.asciidoc
index 31d06571c..23d7edca9 100644
--- a/docs/setup-asp-dot-net.asciidoc
+++ b/docs/setup-asp-dot-net.asciidoc
@@ -49,6 +49,17 @@ such as `.aspx` pages, add the `managedHandler` preCondition to your `web.config
 +
 NOTE: To learn more about adding modules, see the https://docs.microsoft.com/en-us/iis/configuration/system.webserver/modules/add[Microsoft docs].
 
+[NOTE]
+--
+Our IIS module requires:  
+
+* IIS 7 or later
+* Application pool's pipeline mode has to be set to integrated (default for IIS 7 and up)
+* The deployed .NET application must NOT run under quirks mode. This makes `LegacyAspNetSynchronizationContext` the async context handler and can break `HttpContext.Items` correctly 
+restoring when async code introduces a thread switch.
+--
+
+
 . Recompile your application and deploy it.
 +
 The `ElasticApmModule` instantiates the APM agent on the first initialization. However, there may be some scenarios where
diff --git a/docs/troubleshooting.asciidoc b/docs/troubleshooting.asciidoc
index c54452b11..1cab69d2b 100644
--- a/docs/troubleshooting.asciidoc
+++ b/docs/troubleshooting.asciidoc
@@ -173,6 +173,51 @@ You may use the Public Agent API with the `Elastic.Apm.Agent` class in code that
 
 To prevent the `InstanceAlreadyCreatedException` in these scenarios, first use the `Elastic.Apm.Agent.IsConfigured` method to check if the agent is already initialized. After the check, you can safely use other methods in the Public Agent API. This will prevent accidental implicit agent initialization.
 
+[float]
+[[legacy-asp-net-sync-context]]
+=== ASP.NET is using LegacyAspNetSynchronizationContext and might not behave well for asynchronous code
+
+If you see this warning being logged it means your classic ASP.NET Application is running under quirks mode and is using a deprecated but backwards compatible asynchronous context.
+This may prevent our agent from working correctly when asynchronous code introduces a thread switch since this context does not reliably restore `HttpContext.Items`. 
+
+To break out of quirks mode the runtime must be explicitly specified in web.config:
+
+
+[source,xml]
+----
+<httpRuntime targetFramework="4.5" />
+----
+
+Read more about ASP.NET quirks mode here: https://devblogs.microsoft.com/dotnet/all-about-httpruntime-targetframework
+
+[float]
+[[sql-failed-to-remove-from-processing-spans]]
+=== SqlEventListener Failed capturing sql statement (failed to remove from ProcessingSpans).
+
+We log this warning when our SQL even listener is unable to find the active transaction. 
+This has been only observed under IIS when the application is running under quirks mode.
+See "<<legacy-asp-net-sync-context>>" section for more backfround information and possible fixes.
+
+
+[float]
+[[http-no-transaction]]
+=== HttpDiagnosticListenerFullFrameworkImpl No current transaction, skip creating span for outgoing HTTP request
+
+We log this trace warning when our outgoing HTTP listener is not able to get the current transaction.
+This has been only observed under IIS when the application is running under quirks mode.
+See "<<legacy-asp-net-sync-context>>" section for more backfround information and possible fixes.
+
+
+[float]
+[[iis-integrated-pipeline-mode]]
+=== Exception: System.PlatformNotSupportedException: This operation requires IIS integrated pipeline mode
+
+This exception happens if the classic ASP.NET application run under an Application pool that enforces the classic pipeline mode. 
+This prevents our agent to modify headers and thus will break distributed tracing. 
+
+The agent is only supported on IIS7 and higher where the `Integrated Pipeline Mode` is the default.
+
+
 [float]
 [[startup-hook-failure]]
 === Startup hooks failure