This post was migrated from an older system. Some links may point to content that no longer exists. Comments were not migrated.
You’re a web part developer.
As you attempt to import your WebPart onto a page, you receive the following
“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.”
What to do?
From a developer’s standpoint there
are a few things to consider. First, it helps to understand this message
is a generic message
- is applied whenever
an instance of WebPart cannot be created or
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
Why the generic
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
What is the
As mentioned earlier, there are two
failure areas – deserialization errors and
the first thing to check is whether or not a SafeControl entry exists.
- Did you specify the
correct assembly name?
- How about version,
culture, and public key token?
- Did you specify the
- Did you specify the
correct type name?
- Is it
marked as Safe=”true”?
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
- 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
- Ensure the
assembly is properly installed.
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
- 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
- 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
developer has not specified either a DefaultValueAttribute or implemented a ShouldSerializeXXX method for a
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.
- The xml serializer cannot create temp files and/or disk space is
limited. See KB 826786.
- 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
Windows SharePoint Services and Code Access
Access Security Q&A (previous post on this
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
Is more information
available when this problem occurs?
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
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
In short, no information is cached
or recorded. It’s basically wysiwyg.
The exception to
the rule – code access security exceptions are
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.
What causes my page
to blow up and redirect me to the web part maintenance
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
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.