NHibernate Troubleshooting Guide

This page will contain troubleshooting tips for NHibernate. Your input is welcome, the page is editable by all users.

I get an exception from NHibernate

First, a general rule: many exceptions that NHibernate throws are actually wrappers over other exceptions. The underlying exception can be found by examining the InnerException property. This exception may in turn contain another exception and so on. You are usually interested in the innermost exception.

NHibernate.HibernateException: The dialect was not set. Set the property hibernate.dialect.

If you did in fact set the property hibernate.dialect and checked for misspellings then another possible cause of this error is NHibernate not picking up your configuration file. Look through the logs to find out whether this is the case.

Configuration of NHibernate is covered in the documentation.

In short, NHibernate may configured through YourApp.exe.config (commonly known as App.config since Visual Studio renames it automatically during the build), web.config, or hibernate.cfg.xml. In the latter case you need to call Configuration.Configure() for the file to be picked up.

NHibernate behaves in a strange way

When trying to understand why NHibernate behaves in a certain way, it is often very useful to enable logging. See Configuring log4net for use with NHibernate for an example of logging configuration.

I'm changing an object but NHibernate doesn't update the database

NHibernate does not execute SQL statements immediately after you make a change to a persistent object. In fact, it tries to delay SQL execution as far as possible, usually until the time when ITransaction.Commit is called or a query is about to be executed which needs the up-to-date data in the database. If you need to force SQL execution, call ISession.Flush(). But note that using the NHibernate transaction API is usually preferred. Also note that closing a session does not cause a flush.

More details about the flushing process can be found in the documentation.

I get a list with duplicate elements returned when I execute a query

You are most probably experiencing the issue detailed here http://www.hibernate.org/117.html#A12.

TODO: Discussion of other instances of non-obvious behavior.