Invalid Field Name execption when deploying SharePoint custom content types

If you develop custom fields and custom content types in Visual Studio 2010 for SharePoint, you would typically create an Elements.xml that contains all the custom field definitions, and then Content Type files (essentially more Elements.xml) that has elements that reference the custom fields.   Once it's packaged up and deployed, there is often this exception upon feature activation:

12 10:31:54.62  w3wp.exe (0x11B4)                        0x13E4 SharePoint Foundation          Runtime                        tkau Unexpected System.ArgumentException: Invalid field name. {96e21f1d-61e9-449e-be9f-1b6b4a1f25b6} http://myspsite.local/sites/test     at Microsoft.SharePoint.Administration.SPElementDefinitionCollection.ProvisionFieldsAndContentTypes(SPFeaturePropertyCollection props, SPSite site, SPWeb web, Boolean fForce)     at Microsoft.SharePoint.Administration.SPElementDefinitionCollection.ProvisionElements(SPFeaturePropertyCollection props, SPWebApplication webapp, SPSite site, SPWeb web, Boolean fForce)     at Microsoft.SharePoint.SPFeature.Activate(SPSite siteParent, SPWeb webParent, SPFeaturePropertyCollection props, Boolean fForce)     at Microsoft.SharePoint.SPFeatureCollection.AddInternal(SPFeatureDefinition featdef, Version version, SPFeaturePropertyCollection properties, Boolean force, Boolean fMarkOnly)     at ... 34b0893c-1158-4874-8460-e84ef3bb6ef1.....


There are many causes for this particular exception, as well documented in the SharePoint communities.  For example, name collison is a common cause. 

I have discovered a new scenario where the exception can be caused by how the Elements.xml files are ordered in the feature manifest.   In a custom content type Elements.xml, the entries are typically like this if the custom field is already defined:

<fieldref displayname="Widget Name" id="{96E21F1D-61E9-449E-BE9F-1B6B4A1F25B6}" required="FALSE" showineditform="TRUE" showinnewform="TRUE"/>

Notice that there is no Name attribute, because the Name is already defined in the Field definition. 

Now in the feature manifest, if the field definition Elements.xml does not come before any of the content type definition Elements.xml, the above exception would be thrown:

<Feature xmlns="http://schemas.microsoft.com/sharepoint/" Title="My Content Types and Fields" Description="" Id="b02c33b1-aff0-41e5-9511-1b99023c5455" Scope="Site"> <ElementManifests> <ElementManifest Location="Research Page\Elements.xml" /> <ElementManifest Location="News Page\Elements.xml" /> <ElementManifest Location="FieldDefinitions\Elements.xml" /> </ElementManifests> </Feature>

Apparently the feature activation process is not smart enough to figure out the dependency among these and simply goes about it from top to bottom.  To make SharePoint happy, simply move the Elements.xml that contains field definitions to the top:

<Feature xmlns="http://schemas.microsoft.com/sharepoint/" Title="My Content Types and Fields" Description="" Id="b02c33b1-aff0-41e5-9511-1b99023c5455" Scope="Site"> <ElementManifests> <ElementManifest Location="FieldDefinitions\Elements.xml" /> <ElementManifest Location="Research Page\Elements.xml" /> <ElementManifest Location="News Page\Elements.xml" /> </ElementManifests> </Feature>

And the feature can be activated successfully now.