FreeMarker exception handling

FreeMarker is a very flexible templating engine for Java. Exception handling (while rendering the template) is a very important issue for a templating engine. As with JSP the default behaviour of FreeMarker is to completely cancel rendering and display an error page. When developing a webapp this might not be very helpful. Sometimes errors might need to be tolerated; at least for the development phase of the application development.

FreeMarker provides the TemplateExceptionHandler interface with some implementations but we’ll define our own in order to provide a more failsafe and usable behaviour.

public class MyTemplateExceptionHandler 
          implements TemplateExceptionHandler {

  public void handleTemplateException(TemplateException te, 
          Environment env, Writer out) {
    freemarkerlog.error("template error", te);
    try {
      out.write("<span style=\"cursor:help; color: red\" " +
                "title=\"" + ExceptionUtils.getMessage(te) + "\">" +
                "[e]" +
    } catch (IOException ignored) { }

Then, in the code where you configure FreeMarker you need:

config.setTemplateExceptionHandler(new MyTemplateExceptionHandler());

This is what you’ll see whenever there is an exception thrown while rendering the template:
FreeMarker exception handling
A nice little [e] with a tooltip containing the exception message.

6 Responses to “FreeMarker exception handling”

  1. Spiros Tzavellas Says:

    Hi Giannis,

    this is really cool!!! Thanks for sharing!

    I am currently using JSP 2.1 (with tag files) and I am not very happy with it. I am thinking to switch to FreeMarker but the fact that there is no good tool support keeps me bound to JSPs.

    If I am correct you use Netbeans (I use Eclipse btw), do you have any problems with the Netbeans HTML editor when you are editing Freemarker files? Do you use another editor?

  2. cherouvim Says:


    I used to use JSP tag files as well, until I run into some serious problems and the inability to do some funky stuff, so I switched to FreeMarker. It’s very advanced, sometimes too low level; but that makes me happy.

    There is no support for .ftl files in NetBeans. I edit them as plain text with no support from the IDE (all gray, no auto completion, no xml syntax awareness etc). But this issue doesn’t bother me at all, compared to the showstoppers mentioned above.

    Have a look at the FreeMarker manual. There are some mind-blowing stuff in there ;)

  3. Argyro Says:


    yes, it is really annoying that NetBeans does not support Freemarker Templates, though I think that it soon will (see).
    I thought that Eclipse did support .ftl. I have chosen that NetBeans renders .ftl files as HTML objects, so html looks fine and you can separate html and FreeMarker tags. Sometimes I use Textpad (there is an ftl syntax) for convenience when minor corrections are involved.

    Anyway, the functionalities that FreeMarker provides you with (any many of them out of the box) is more than enough for me to live without the auto-completion and colorless. It is very easy to learn and use in general, and the most advanced users can take advantage of its flexibility and high level functions. Plus, it’s fun and surprising!

    Give it a try! :-)

  4. Spiros Tzavellas Says:

    Since Freemarker is “mind-blowing”, “fun” and “surprising” I will probably give it a try :-)


    I know about the Eclipse plug-in, I’ve tried it in the past but it wasn’t good enough.

    Thanks for your replies.

  5. dimzava Says:


    Indeed, freemarker offers some really cool stuff that compensates for the lack of a proper editor, although I have to say that sometimes I miss that familiar feeling of JSPs :-)

  6. Harald Walker Says:

    I like you tooltip solution. Much nicer than the long error message.