Suzanne Cook's .NET CLR Notes : Loader Debugging Advice

Debugging an InvalidCastException

Suzanne Cook — Thu, 03 Jun 2004 04:57:00 GMT

First, obviously, find the two types for which the cast failed and verify that they are the same type or otherwise castable.

Next, if the type was just deserialized, also verify that its assembly successfully loaded in the target appdomain.

If everything seems fine, check to see if the assemblies for those two types are loaded from different locations and in the same appdomain. (The actual cast is done in just one appdomain, even if the exception happens when passing a type between two appdomains.) Even if the bits of those assemblies are totally identical, if they are loaded from different paths, they will be considered different, so their types will be considered different. (See Comparing Already-Loaded Assemblies.)

A quick way to check for that is to examine the loaded module window of a debugger to see if that assembly was loaded multiple times. If it was, break on module loads to get the callstack for the unexpected load. If that's inconvenient, try getting the Fusion log.

Usually, the problem is that:

The assembly is available in the GAC (or the ApplicationBase) and loaded there by static reference (something was compiled against that assembly).
It has also been loaded dynamically by path, from another path (LoadFrom(), LoadFile(), etc.).
Then, the code tries to cast the type from (2) to the corresponding type from (1).

To fix this, once you find the offending caller, you will need to either cause the two types to be loaded from the same assembly from the exact same path, or avoid doing the cast. To decide between the assemblies at paths (1) and (2), see Choosing a Binding Context. Usually, I recommend using (1) - see Switching to the Load Context for help with implementing that.

Debugging a MissingMethodException, MissingFieldException, TypeLoadException

Suzanne Cook — Sat, 14 Feb 2004 03:03:00 GMT

Say you've just installed some assemblies from a third party and now you're seeing a MissingMethodException, MissingFieldException, or TypeLoadException (during the run of an application using those assemblies). Below are the common causes.

Loading failures
First, check for assembly binding failures by getting the Fusion log. Look for the assembly containing that method/field/type or assemblies containing types referenced by it. If an assembly failed to load, use the instructions at the same link to help resolve that issue.

Unexpected assembly version loaded
But, if that's not the problem, turn on the Fusion log for everything - not just failures - and check to see if the wrong version of those assemblies is being loaded. Look at the display names requested. Are any requesting outdated versions, even after policy has been applied (see further down in the log for the post-policy display name)? If so, you may want to recompile part of your app so that it has current references.

Loaded from unexpected path
If that doesn't help, run filever.exe on the file at the path it was loaded from. You can get that from the loaded modules list in a debugger. It's also the last path listed in the Fusion log, for a successful log (if it's in the GAC, no path is listed). Make sure it is the same path as you would expect.

Not in this version of the assembly
Next, run ildasm.exe on the file at the path it was loaded from at runtime. Make sure that the method/field/type is there and is defined how you would expect it. Maybe the file has changed, adding or removing methods or the like, but the assembly version and location have stayed the same.

Invalid IL
Now, try running peverify.exe on the file containing the method/field/type using the path it was loaded from at runtime. If it gives an error, check back to see if there was a warning at compile-time for this file.

Where to Find Technical Support

Suzanne Cook — Sat, 06 Dec 2003 02:13:00 GMT

Microsoft's official support website is http://support.microsoft.com/. It has all kinds of resources like product FAQs, downloads, searchable KB articles, newsgroup pointers, and ways to reach people to help with your individual needs or feedback.

Unfortunately, I can't give attention to individual customer issues. That's because I work in product design and development, not customer support. Someone has to be focused on that or else we'd never ship anything! So, I'm going to have to leave your questions and comments to MS's official channels which specialize in that. Please keep comments you post here general and about the loader or performance.

Determining the Referencing Assembly

Suzanne Cook — Sat, 15 Nov 2003 10:23:00 GMT

Say you're debugging your application and you see that version 1.0 of an assembly is being loaded when you thought it should be version 2.0. Where is the reference to 1.0 coming from?

The easiest way to find out is to look at the Fusion log for this bind. If the version 1.0 assembly was successfully loaded, use the ForceLog/"Log all binds" option of FusLogVw. Then, look for the line in the log showing the calling assembly:

Calling assembly : referencingAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=12ab3bf24c56c45b.

It shows the display name of the calling assembly when available. It doesn't tell you whether this is a static or a dynamic reference because Fusion doesn't know or care (that doesn't matter for binding purposes). So, this could mean that referencingAssembly was built against the other 1.0 assembly, or that it asked for it at runtime via Assembly.Load(), etc.

Sometimes the calling assembly is not specified in the log. There are a few possible cases where that happens:

The assembly was requested by unmanaged code (interop).
The calling assembly was in another appdomain (AppDomain.CreateInstance(), etc.).
The calling assembly had not been loaded through Fusion (Assembly.Load(byte[]), Assembly.LoadFile(), etc.).

ReflectionTypeLoadException

Suzanne Cook — Tue, 12 Aug 2003 01:40:00 GMT

If a type can't be loaded for some reason during a call to Module.GetTypes(), ReflectionTypeLoadException will be thrown. Assembly.GetTypes() also throws this because it calls Module.GetTypes().

The Message for this exception is "One or more exceptions have been thrown while loading the types" or "Unable to load one or more of the types in the assembly", which doesn't seem very descriptive. But, the exception actually provides more info that that. Just get the LoaderExceptions property of the ReflectionTypeLoadException instance. That will give an array of the exceptions caught while loading all of the types from the module. If the exceptions are due to an assembly loading problem, see my general debugging advice.

Debugging Assembly Loading Failures

Suzanne Cook — Fri, 30 May 2003 00:09:00 GMT

So...you're seeing a FileNotFoundException, FileLoadException, BadImageFormatException or you suspect an assembly loading failure? Try the steps below to start your debugging process.

First, get the Message property from the exception. If the exception's InnerException property is set, get the Message property from that. If the message is generic, also get the hresult by calling System.Runtime.InteropServices.Marshal.GetHRForException(), passing in the Exception object. If that info is not readily available, you may need to attach a debugger and set it to catch managed exceptions. Then, get the hresult by retrieving the private _HResult field of the managed Exception object.

Retrieving the Fusion log

If the exception message isn t enough for you to determine what the problem is, try getting the Fusion log. It will describe the binding failure (if this is due to an assembly binding failure, instead of a loading failure after the file is found). The exception may already include the log. If not, to get it, run fuslogvw.exe. If you don't have fuslogvw.exe already, install the Framework SDK.

For pre-v2.0: click on "Log Failures." If this is an ASP.NET or .NET Windows service app, select the Custom option and using regedit, set [HKLM\Software\Microsoft\Fusion\LogPath] to point to an existing directory (like c:\mylogs, not c:\). If you need to log all binds, not just failing ones, set [HKLM\Software\Microsoft\Fusion\ForceLog] as a DWORD value to 1.
For v2: click on "Settings," then choose "Log bind failures to disk" if you only care about the failures or "Log all binds to disk" if you want to see all binding requests.
To turn on failure logging during a test run instead of by hand, have your script set [HKLM\Software\Microsoft\Fusion\LogFailures] as a DWORD value to 1 using regedit.

Then, click "OK." Now, re-run the process. Next, click "Refresh" in fuslogvw, and a line should appear for each binding failure (or for each bind, if ForceLog is set). Now, double-click on the line in the "Application" column for the interesting bind, and a web page should come up with the Fusion log.

If the file was found, it was loaded from the last path probed in the log (or from the GAC, if there is no probed path shown).

Note: Unless you are explicitly debugging the failure of a resource to load, you will likely want to ignore failures to find assemblies with the ".resources" extension with the culture set to something other than "neutral". Those are expected failures when the ResourceManager is probing for satellite assemblies.

Troubleshooting Fusion logging

Keep in mind that there may not be any entries if there were no binds or if there were no binding failures (when logging failures only). (And don't forget to restart your application's process after changing logging settings.) If there are not as many entries as you expect, you may need to clear your download cache to make room for them. To do that, in Internet Explorer, choose “Tools“, “Internet Options“, “Delete Files”, “OK“, then re-run your app and finally click “Refresh“ again in fuslogvw.

There is only one Fusion log saved per display name/codebase. So, if the same exact reference is requested twice in the same process, it will only show up once in fuslogvw. To see the duplicate logs, you'll need to stop execution (for example, with breakpoints in your debugger) and then get the log at that time.

For FileNotFoundException:
At the bottom of the log will be the paths that Fusion tried probing for this assembly. If this was a load by path (as in Assembly.LoadFrom()), there will be just one path, and your assembly will need to be there to be found. Otherwise, your assembly will need to be on one of the probing paths listed or in the GAC if it's to be found.

You may also get this exception if an unmanaged dependency or internal module of the assembly failed to load. Try running depends.exe on the file to verify that unmanaged dependencies can be loaded. Note that if you re using ASP.NET, the PATH environment variable it's using may differ from the one the command line uses. If all of them could be loaded, try ildasm.exe on the file, double-click on "MANIFEST" and look for ".file" entries. Each of those files will need to be in the same directory as the manifest-containing file.

For BadImageFormatException:
Try running peverify.exe on the file. That will give a more specific description about why it s considered a bad image. Keep in mind that modules built against v2 can not be loaded by a pre-v2 CLR.

For SecurityException:
You need Execute permission for loading any assembly. Also, if a codebase was used to load this file, you would need both FileIOPermission.Read and FileIOPermission.PathDiscovery or else WebPermission to the location (depending on whether this is a local file or a URL). Try caspol.exe to check your managed security settings.

For FileLoadException:

For an "Access is denied" message (for hresult E_ACCESSDENIED, 0x80070005):
Run tlist -m on the file to see if another process has the file locked and without share-read access. If not, check the ACLs for the file and its dependencies (especially if you're using impersonation).

For a "The located assembly's manifest definition with name [yourAssembly] does not match the assembly reference" message (for hresult FUSION_E_REF_DEF_MISMATCH, 0x80131040):
The Fusion log will say which part of the assembly reference failed to match what was found. It will be the assembly name, culture, public key (or token) or version (if the found assembly was strongly-named).

For "Unverifiable image [yourAssembly] can not be run" or "Can not run executable [yourAssembly] because it contains relocations" messages (for hresult COR_E_FIXUPSINEXE, 0x80131019):
That image must be run as the process exe or else be compiled as a dll. This is because MC++ has made optimizations for you in your image, based on the assumption that it will be the process exe. If it's not the process exe, it won t be loaded at the expected location, so the assumed offsets will be incorrect. When the CLR sees such a file loaded as a non-process exe, it will reject the load.