You’re a web part developer.  As you attempt to import your WebPart onto a page, you receive the following error:

“A Web Part or Web Form Control on this Web Part Page cannot be displayed or imported because it is not registered on this site as safe.”

From a developer’s standpoint there are a few things to consider.  First, it helps to understand this message is a generic message that

1. is applied whenever an instance of WebPart cannot be created or
2. is disallowed, either explicitly or implicitly, from rendering via the SafeControls list. 

These two conditions are very important to remember as they will help you track down the problem.

Historically it all comes down to security and the desire to not confuse users.  In the original form, a wide variety of error message were presented to the user; however, it was determined the error messages were too verbose (thus, potentially leading to questions like “and this relates to me how?”) and often times revealed too much information about the server’s configuration (information disclosure of server configuration is a big no-no).  The design team even tossed around the idea of hinging the verbose error messages to a toggle of some sorts, but the cost of wiring everything outweighed the benefits.  On top of that, the maintenance required to “translate” error conditions into user friendly context was also undesirable due to complexity and the unbounded number of possible error messages.  Therefore, the decision was made to fit web parts into two buckets – those that can be rendered and those which cannot.  For those which cannot, they are generically stamped as being unsafe.

As mentioned earlier, there are two failure areas – deserialization errors and administrative actions.

1. Obviously, the first thing to check is whether or not a SafeControl entry exists.
   1. Did you specify the correct assembly name?
   2. How about version, culture, and public key token? 
   3. Did you specify the correct namespace?
   4. Did you specify the correct type name?
   5. Is it marked as Safe=”true”?

For the assembly name, I always recommend using the assembly full name instead of simply using the assembly name.  Why?  It’s better resolution and provides you with guaranteed operation with FP2003 (it has an issue where non-strongly named assemblies need to be referenced by the full name).
 

2. Check if the DWP matches the SafeControl entry. 
   
   You would be surprised how many times folks get this simple requirement wrong.  Open up your dwp and verify the entries in the web.config matches your dwps.
3. Ensure the assembly is properly installed.
   
   The SharePoint Configuration Analyzer can help you isolate problems associated with hints 1 and 3.
   
   If you want a handy tool which will generate the correct SafeControl and DWPs, check out InstallAssemblies.exe which is available in the Web Part Toolkit, which shipped with the Resource Kit.

4. The web part is unable to initialize because an unhandled exception occurs in either the constructor or a property setter.
   
   This is the number one gotcha for most developers.  A classic example of how this manifests itself can be seen when code access security permissions are tightened or perhaps moving usage from an SPS site over to a WSS site (or vice versa).
5. A custom namespace for the web part properties has not been provided.  The developer must specify a custom namespace at either the class level or the property level.
6. The developer has not specified either a DefaultValueAttribute or implemented a ShouldSerializeXXX method for a property.
7. The developer has forgotten to remove wildcard versioning for the assembly.  This results in a mismatch between the SafeControl/dwp and the assembly itself each time the assembly is compiled.
   
   The last three are the most common newbie problems.  Once you’ve written a couple of parts, this practically becomes a non-issue.
8. The xml serializer cannot create temp files and/or disk space is limited. See KB 826786.
   
9. Is your web part referencing a library and is running with less than Full trust?  If so, your web part may not be allowed to load unless the APTCA bit is enabled on the library assembly.
   
   

For more information on code access security, please read the following documents and posts:

·         Microsoft Windows SharePoint Services and Code Access Security

·         Code Access Security Q&A (previous post on this site)

Security note: Developers new to code access security should take the time to understand the requirements of running as partially trusted code, but more importantly what it may mean to them if they build library assemblies with AllowPartiallyTrustedCallers attribute set.

Yes and no.  In some instances, the very first time a deserialization error occurs (4-8), the error message presented to the user may actually contain a more descriptive context (i.e. “no default value has been specified”).  However, all subsequent occurrences will result in the "cannot deserialize the Web Part" error message.

“Web Part Error: One of the properties of the Web Part has an incorrect format. Windows SharePoint Services cannot deserialize the Web Part. Check the format of the properties and try again.”

If you don’t see the deserialization error, you will see the “not registered on this site as safe” message.  The reason “proper” error messages are only seen on first render is simply because the errors are not cached and, therefore, subsequent hits fall through to the generic error message.

In short, no information is cached or recorded.  It’s basically wysiwyg.

In the event a code access security exception is encountered, the exception is recorded in the server’s application event log.  This applies to the SecurityException and PolicyException exceptions only. 

If you import a web part onto a page and you are immediately redirected to the web part maintenance page (aka. the contents page), this is an indication that an exception was thrown and not properly handled by the web part.  If this is the case, your web part has met the requirements for a SafeControl and is actually executing.  It’s now your job as the developer to determine why the exception was thrown and how to best handle it.... :)

Many folks argue that there should be more than two buckets... I agree, but knowing what causes the error certainly helps narrow down the scope.

-Maurice