This document is about: SERVER 5

This page is a work in progress and could be pending updates.

Exception Handling


Exceptions not handled by the developers code will always raise the unhandled exception event handler. We encourage developers to implement the unhandled exceptions handler but in all cases, unhandled exceptions are logged by Photon. For details see "Logging Unhandled Exceptions". Photon supports one of two policies when an unhandled exception is raised: Ignore and TerminateProcess.

There are a couple of cases where the exception handling policy might be overridden by the CLR, examples:

Note: the "Application Compatibility Flag" (legacyUnhandledExceptionPolicy) described in "Exceptions in Managed Threads" isn't supported by Photon on a per application config. This mode is set per instance (UnhandledExceptionPolicy = "Ignore") - see "Configuring the UnhandledException Policy".

New With Photon 5.0

"ReloadAppDomain" policy is obsolete and no longer supported as an "UnhandledExceptionPolicy" value for the "Runtime" node. "TerminateProcess" is now the default value if none is specified and it's also the value set in the configuration file delivered in the SDK.

Suggestions For the Usage Of the UnhandledExceptionPolicies

Microsoft introduced the "TerminateProcess" as new default policy with .NET 2.0 with following statement quoted from "Exceptions in Managed Threads":

When threads are allowed to fail silently, without terminating the application, serious programming problems can go undetected. This is a particular problem for services and other applications which run for extended periods. As threads fail, program state gradually becomes corrupted. Application performance may degrade, or the application might hang.

Allowing unhandled exceptions in threads to proceed naturally, until the operating system terminates the program, exposes such problems during development and testing. Error reports on program terminations support debugging.

But depending on the stage or situation your project is (in development, in QA, LIVE without known issues, etc.) you might consider using one of the different policies supported by Photon:

  • Ignore
  • TerminateProcess


While developing setting "TerminateProcess" launches the debugger/visual studio on process termination. Are you handling with a multithreaded issue you might prefer to keep the process running and the application loaded then setting the policy "Ignore" would be what you prefer.


During a QA Phase, either during the run of stress tests or manual testing, using "TerminateProcess" ensures you won't get flooded by errors that stem from the root-error.

Live Stable

Assuming your service is stable a policy you can consider using is the "Ignore". In the rare event of an unhandled exception the application would be restarted by Photon minimizing the risks. This is the fastest way for the system to be up again. Faster than setup Photon as a Service with "TerminateProcess" as policy and the auto-restart windows services feature. Note: you should monitor your service and log files in case this happens more often.

Live With A Known Issue

If the system shows an unexpected exception quite often and you need time to fix - depending on the exception it might be possible to keep a reasonably stable system by setting the policy to "Ignore".

Note on StackOverflows

Usually the stacktrace logged during the unhandled exception will point you to the fix. The StackOverflowException is a case where the stacktrace can get lost if the unhandled exception policy is set to "Ignore". See "Photon Server Stackoverflow" page for steps on how to debug it.

Note on Debugging Core

For the rare cases where the Photon core raises an unexpected exception we recommend setting "ProduceDump" to TRUE (See "Photon Core Debugging"). Sending us the generated dump files and logs will help us to fix the issue.

Logging Unhandled Exceptions

As depicted in the figure below an unhandled exception event is raised first in the context of the custom application (1) where the developer can log the exception in any way he requires to c) - also refer to sample code in LoadBalancing. In a second step the CLR then raises the event in the default application domain (2) - which in the case of Photon is the PhotonHostRuntime.Because of this Photon is able to log the exception in b).

photon server: logging unhandled exceptions
Photon Server: logging unhandled exceptions

Photon Log files default path/filenames:

  • a) [$PhotonBaseDir]\bin_[$OS]\log\Photon-[$InstanceName]-[$date].log
  • b) [$PhotonBaseDir]\bin_[$OS]\log\PhotonCLR.log
  • c) [$PhotonBaseDir]\log\[$ApplicationName].log

Configuring the UnhandledException Policy


      Assembly="PhotonHostRuntime, Culture=neutral"
  • UnhandledExceptionPolicy: Ignore or TerminateProcess.

Photon Core Debugging


   <!-- Instance settings -->
        ProduceDumps = "TRUE"
        DumpType = "Full"
        MaxDumpsToProduce = "2"

If a server crashes and the reason for it is not found in the logs, Photon can be configured to create dump files. These reflect the state and memory of the crash and are invaluable to debug these cases.

Once a dump file is written, you can zip it with the logs and mail it to us with a description of the issue. In most cases, we will get in touch with you to get more information and solve the case.

  • ProduceDumps: TRUE or FALSE. Switch to enable or disable creation of "dump files" in case of a crash. Dump files are essential to find issues in the Photon Core.
  • DumpType: Defines the type of crash dumps to write. The types are Full or Maxi or Mini and they include less information from first to last but also require less storage space.
  • MaxDumpsToProduce: Configures how many dump files are written maximum. If the files are moved or deleted, new ones can be written.
  • MaxDumpsToAttemptToProduce: Configures maximum dump files creation attempts.
Back to top