Type: Troubleshooting
Category: Umbraco Cloud > Monitor & Troubleshoot
Tags: boot failed, BootFailedException, Umbraco cannot run, no error message, blank error page, debug mode, Hosting Debug, appsettings.Development.json, log files, Kudu, Power Tools

Product: Umbraco CMS, Umbraco Cloud
Version: All versions

Summary

If your site fails to boot and all you see is a generic Boot failed: Umbraco cannot run page with no further detail, the underlying exception is not missing. It is being hidden by the Debug setting, and it is still written to the log file. This article shows you both ways to get at the real error message.

Symptoms

An environment returns a generic error page reading Boot failed: Umbraco cannot run. See Umbraco's log file for more details., or your own BootFailed.html page.
The Cloud Portal or your monitoring shows only Umbraco is not yet ready. Level: BootFailed and Application is shutting down..., with no stack trace.
The same code boots without problems on your local machine.
The environment that fails is a Development or Staging environment, where you would expect to see developer error detail.

Cause

Umbraco decides how much boot-failure detail to show in the browser based on Umbraco:CMS:Hosting:Debug. The default value is false. When it is false, the browser gets the generic boot-failed page instead of the detailed developer exception page.

This catches people out on Development environments in particular, because the setting can be false in appsettings.Development.json even when the environment name suggests debug detail should be on. The environment name and the Debug setting are independent of each other.

The exception itself is never lost. As the Umbraco documentation puts it: "The full error can always be found in the log file."

Solution

Option 1: Read the log file (recommended, no deployment needed)

This is the fastest route, and it does not change any configuration.

In the Umbraco Cloud Portal, click the arrow next to the environment name and select Logs.
Look for the entry at the time the site tried to start. The boot failure is logged at Error level, typically with the message Unattended upgrade failed. or Boot failed., followed by the full exception and stack trace.
If you would rather read the raw files, open Power Tools (Kudu) for the environment and browse to ~/site/wwwroot/umbraco/Logs/.

All timestamps in Cloud log files are in UTC, which may not match your local time zone.

Option 2: Turn debug mode on temporarily

If you want the exception rendered in the browser, set Debug to true for the affected environment:

"Umbraco": {
  "CMS": {
    "Hosting": {
      "Debug": true
    }
  }
}

Place this in the appsettings file that applies to the environment you are debugging, for example appsettings.Development.json, then deploy and reload the site. The detailed developer exception page replaces the generic boot-failed page.

Set it back to false when you are done. Debug mode exposes stack traces and internal paths to anyone who can reach the site, so it should never be left on for a publicly reachable environment, and never on Live.

Prevention

Before escalating a boot failure, check the log file first. A boot failure with "no error message" almost always has a full stack trace waiting in umbraco/Logs.
When you raise a support ticket for a boot failure, include the exception from the log file rather than only the generic page. It removes a full round trip from the investigation.
Be aware that Debug may differ per environment, and that a file named for the Development environment does not automatically mean debug detail is switched on.

Still having issues?

If you have the exception from the log file but are not sure what it means, open a support ticket and include the full stack trace, the environment it happened on, and your CMS, Forms and Deploy versions.

Boot failure shows no error details when debug mode is off