13 KiB

Raw Blame History

title	author	description	manager	ms.author	ms.custom	ms.date	ms.prod	ms.technology	ms.topic	uid
Troubleshoot ASP.NET Core on Azure App Service	guardrex	Learn how to diagnose problems with ASP.NET Core Azure App Service deployments.	wpickett	riande	mvc	01/31/2018	asp.net-core	aspnet	article	host-and-deploy/azure-apps/troubleshoot

Troubleshoot ASP.NET Core on Azure App Service

By Luke Latham

[!INCLUDEAzure App Service Preview Notice]

This article provides instructions on how to diagnose an ASP.NET Core app startup issue using Azure App Service's diagnostic tools. For additional troubleshooting advice, see Azure App Service diagnostics overview and How to: Monitor Apps in Azure App Service in the Azure documentation.

App startup errors

502.5 Process Failure
The worker process fails. The app doesn't start.

The ASP.NET Core Module attempts to start the worker process but it fails to start. Examining the Application Event Log often helps troubleshoot this type of problem. Accessing the log is explained in the Application Event Log section.

The 502.5 Process Failure error page is returned when a misconfigured app causes the worker process to fail:

500 Internal Server Error
The app starts, but an error prevents the server from fulfilling the request.

This error occurs within the app's code during startup or while creating a response. The response may contain no content, or the response may appear as a 500 Internal Server Error in the browser. The Application Event Log usually states that the app started normally. From the server's perspective, that's correct. The app did start, but it can't generate a valid response. Run the app in the Kudu console or enable the ASP.NET Core Module stdout log to troubleshoot the problem.

Connection reset

If an error occurs after the headers are sent, it's too late for the server to send a 500 Internal Server Error when an error occurs. This often happens when an error occurs during the serialization of complex objects for a response. This type of error appears as a connection reset error on the client. Application logging can help troubleshoot these types of errors.

Default startup limits

The ASP.NET Core Module is configured with a default startupTimeLimit of 120 seconds. When left at the default value, an app may take up to two minutes to start before the module logs a process failure. For information on configuring the module, see Attributes of the aspNetCore element.

Troubleshoot app startup errors

Application Event Log

To access the Application Event Log, use the Diagnose and solve problems blade in the Azure portal :

In the Azure portal, open the app's blade in the App Services blade.
Select the Diagnose and solve problems blade.
Under SELECT PROBLEM CATEGORY, select the Web App Down button.
Under Suggested Solutions, open the pane for Open Application Event Logs. Select the Open Application Event Logs button.
Examine the latest error provided by the IIS AspNetCoreModule in the Source column.

An alternative to using the Diagnose and solve problems blade is to examine the Application Event Log file directly using Kudu:

Select the Advanced Tools blade in the DEVELOPMENT TOOLS area. Select the Go→ button. The Kudu console opens in a new browser tab or window.
Using the navigation bar at the top of the page, open Debug console and select CMD.
Open the LogFiles folder.
Select the pencil icon next to the eventlog.xml file.
Examine the log. Scroll to the bottom of the log to see the most recent events.

Run the app in the Kudu console

Many startup errors don't produce useful information in the Application Event Log. You can run the app in the Kudu Remote Execution Console to discover the error:

Select the Advanced Tools blade in the DEVELOPMENT TOOLS area. Select the Go→ button. The Kudu console opens in a new browser tab or window.
Using the navigation bar at the top of the page, open Debug console and select CMD.
Open the folders to the path site > wwwroot.
In the console, run the app by executing the app's assembly.
- If the app is a framework-dependent deployment, run the app's assembly with dotnet.exe. In the following command, substitute the name of the app's assembly for <assembly_name>: dotnet .\<assembly_name>.dll
- If the app is a self-contained deployment, run the app's executable. In the following command, substitute the name of the app's assembly for <assembly_name>: <assembly_name>.exe
The console output from the app, showing any errors, is piped to the Kudu console.

ASP.NET Core Module stdout log

The ASP.NET Core Module stdout log often records useful error messages not found in the Application Event Log. To enable and view stdout logs:

Navigate to the Diagnose and solve problems blade in the Azure portal.
Under SELECT PROBLEM CATEGORY, select the Web App Down button.
Under Suggested Solutions > Enable Stdout Log Redirection, select the button to Open Kudu Console to edit Web.Config.
In the Kudu Diagnostic Console, open the folders to the path site > wwwroot. Scroll down to reveal the web.config file at the bottom of the list.
Click the pencil icon next to the web.config file.
Set stdoutLogEnabled to true and change the stdoutLogFile path to: \\?\%home%\LogFiles\stdout.
Select Save to save the updated web.config file.
Make a request to the app.
Return to the Azure portal. Select the Advanced Tools blade in the DEVELOPMENT TOOLS area. Select the Go→ button. The Kudu console opens in a new browser tab or window.
Using the navigation bar at the top of the page, open Debug console and select CMD.
Select the LogFiles folder.
Inspect the Modified column and select the pencil icon to edit the stdout log with the latest modification date.
When the log file opens, the error is displayed.

Important! Disable stdout logging when troubleshooting is complete.

In the Kudu Diagnostic Console, return to the path site > wwwroot to reveal the web.config file. Open the web.config file again by selecting the pencil icon.
Set stdoutLogEnabled to false.
Select Save to save the file.

[!WARNING] Failure to disable the stdout log can lead to app or server failure. There's no limit on log file size or the number of log files created.

For routine logging in an ASP.NET Core app, use a logging library that limits log file size and rotates logs. For more information, see third-party logging providers.

Common startup errors

See the ASP.NET Core common errors reference. Most of the common problems that prevent app startup are covered in the reference topic.

Slow or hanging app

When an app responds slowly or hangs on a request, see Troubleshoot slow web app performance issues in Azure App Service for debugging guidance.

Remote debugging

See the following topics:

Remote debugging web apps section of Troubleshoot a web app in Azure App Service using Visual Studio (Azure documentation)
Remote Debug ASP.NET Core on IIS in Azure in Visual Studio 2017 (Visual Studio documentation)

Application Insights

Application Insights provides telemetry from apps hosted in the Azure App Service, including error logging and reporting features. Application Insights can only report on errors that occur after the app starts when the app's logging features become available. For more information, see Application Insights for ASP.NET Core.

Monitoring blades

Monitoring blades provide an alternative troubleshooting experience to the methods described earlier in the topic. These blades can be used to diagnose 500-series errors.

Confirm that the ASP.NET Core Extensions are installed. If the extensions aren't installed, install them manually:

In the DEVELOPMENT TOOLS blade section, select the Extensions blade.
The ASP.NET Core Extensions should appear in the list.
If the extensions aren't installed, select the Add button.
Choose the ASP.NET Core Extensions from the list.
Select OK to accept the legal terms.
Select OK on the Add extension blade.
An informational pop-up message indicates when the extensions are successfully installed.

If stdout logging isn't enabled, follow these steps:

In the Azure portal, select the Advanced Tools blade in the DEVELOPMENT TOOLS area. Select the Go→ button. The Kudu console opens in a new browser tab or window.
Using the navigation bar at the top of the page, open Debug console and select CMD.
Open the folders to the path site > wwwroot and scroll down to reveal the web.config file at the bottom of the list.
Click the pencil icon next to the web.config file.
Set stdoutLogEnabled to true and change the stdoutLogFile path to: \\?\%home%\LogFiles\stdout.
Select Save to save the updated web.config file.

Proceed to activate diagnostic logging:

In the Azure portal, select the Diagnostics logs blade.
Select the On switch for Application Logging (Filesystem) and Detailed error messages. Select the Save button at the top of the blade.
To include failed request tracing, also known as Failed Request Event Buffering (FREB) logging, select the On switch for Failed request tracing.
Select the Log stream blade, which is listed immediately under the Diagnostics logs blade in the portal.
Make a request to the app.
Within the log stream data, the cause of the error is indicated.

Important! Be sure to disable stdout logging when troubleshooting is complete. See the instructions in the ASP.NET Core Module stdout log section.

To view the failed request tracing logs (FREB logs):

Navigate to the Diagnose and solve problems blade in the Azure portal.
Select Failed Request Tracing Logs from the SUPPORT TOOLS area of the sidebar.

See Failed request traces section of the Enable diagnostics logging for web apps in Azure App Service topic and the Application performance FAQs for Web Apps in Azure: How do I turn on failed request tracing? for more information.

For more information, see Enable diagnostics logging for web apps in Azure App Service.