For all of its power and glory NHibernate is no different than any other tool which requires you to configure it before you can use it.  In the case of NHibernate you need to configure (map) each of the tables you want to access to the various entities in which they are going to populate.  And because you need to manually configure this, there is room for mistakes and errors. 

I wanted to outline some mapping errors I have run into while trying to learn NHibernate and explain how to resolve them.  We will be utilizing the FluentNhibernate mapping library to ease the process of creating our NHibernate mappings.

Common Issue #1 – Wrong/Invalid Table Name Used In Mapping

Issue: When the mapping from an entity to the table is not valid you will receive the below error.

Error: System.Data.SqlClient.SqlException: Invalid object name ‘YourNameHere’

Solution:

1. Ensure that the entity name you are mapping is the same as the database table.
2. Add WithTable( "TableNameHere" ); command to your mapping file.

Common Issue #2 – Missing primary key mapped for the table

Issue: when creating the mapping you fail to provide the primary key mapping for a table (Id() or UseCompositeId())

Error: System.Xml.Schema.XmlSchemaValidationException: The element 'class' in namespace…List of possible elements expected: 'meta, jcs-cache, cache, id, composite-id' in namespace'

Solution:

1. Add a mapping for the primary key for your entity

Common Issue #3 – Wrong/Invalid Column Name Used In Mapping

Issue: When the mapping from an entity to the table is not valid you will receive the below error.

Error: System.Data.SqlClient.SqlException: Invalid column name 'YourColumnNameHere.

Solution:

1. Check the mapping for your class/table and ensure that you have not provided the wrong database column name for your property

Common Issue #4 – Missing/Invalid property name mapping on Many-to-One, One-to-Many or Many-to-Many

Issue: When you setup your mapping to map to a backing field (_SomeField), but the name of the backing field you provide is not valid

Error: NHibernate.PropertyNotFoundException: Could not find field '_someField in class 'Full.Class.Name.Path.Here'

Solution:

1. Check you entity to make sure you have the spelling of your backing field correctly.
2. If you are using FluentNhibernate for your mapping make sure that your backing field name matches your property name, with the exception of the prefix (‘_’ or ‘m’).

Common Issue #5 – Could not find a Setter for a mapping

Issue: When you are trying to push data either into a backing field and you fail to provide the ‘access modifier’ or your property does not have a public ‘Setter’

Error: NHibernate.PropertyNotFoundException: Could not find a setter for property 'PropertyNameHere' in class 'Full.Class.Name.Path.Here’

Solution:

1. If you are using a backing field, make sure you provide the access modifier. 
   .Access.AsCamelCaseField( Prefix.Underscore ) If using FluentNHibernate
2. If you are not using a backing field, make sure your property has a public setter

Common Issue #6 – Fail to mark property or method as void for a class which is mapped

Issue: When creating your property or method on your class you forget to mark a class as virtual.

Error: NHibernate.InvalidProxyTypeException: The following types may not be used as proxies: ‘Some.Type.here’

Solution:

1. Read the exception and mark the appropriate class as virtual.

Common Issue #7 – Invalid column foreign key mapping for a Many-To-One mapping

Issue: When trying to setup a mapping for a Many-to-One mapping the FK mapping is not setup correctly when the FK property name is different from the column name

Error: System.Data.SqlClient.SqlException: Invalid column name ‘SomeColumnName_id'

Solution:

1. Ensure that you the spelling of your column name mapping correct.
2. Add the syntax to manually map the FK column name using the .TheColumnNameIs("SomeColumnName`_ID") syntax (FluentNHibernate)

The 7 common issues I talked about above are in no way ALL the possible issues that you may come across, they are simply some that I have seen. I hope this helps someone else solve their problems.

Till next time,