General

Q: I see something wrong! Can someone fix it? I want someone to enter in my additional FAQ or other information.

Actually, anyone can do this! Just sign up for a Confluence account on Codehaus using the link from the login form after clicking on the pencil icon in the corner to edit the page. If you already have a Codehaus account, just sign in as you normally would.

Q: After deployment as a WAR Grails becomes unresponsive when placed under load! What can I do?

The way Groovy's MetaClass system operates within Grails requires the Server VM. Grails cannot be deployed on the client VM and typically you need to assign more memory to the VM too. A good combination of settings to pass to the VM to run Grails is:

-server -Xmx512M

Q: OMG I get OutOfMemoryErrors or PermGen Space errors when running Grails in development mode. What do I do?

Since Grails 0.6, Grails automatically re-compiles Java sources and domain classes using pre-compilation and then a server restart. This can lead to permgen space running out if the server is run for a long time and many changes are made. You can disable this feature if it is not important to you with:

grails -Ddisable.auto.recompile=true run-app

There is also a problem with Grails 0.6 on Windows where you get OutOfMemoryErrors during a period of activity in development mode due to the re-compilation. This may be solved in SVN head, but if you see this problem the above option can also help.

For other distributions, simply download and install a Sun JDK and make sure that its {{bin}} directory comes before the GNU java in the path.

Note that this is likely to occur with Ubuntu and OpenSUSE. Other distributions probably package GNU java as well, but these two are confirmed.

Q: I get an exception when loading my Grails application in my browser

One thing to always check in case of unexpected exceptions is the value of the CLASSPATH variable in your console. Run {{set CLASSPATH}} on Windows and {{echo $CLASSPATH}} on Mac OS X, Linux and Unix to print the value. Grails does not depend on the CLASSPATH variable so in case it's set run {{set CLASSPATH=}} on Windows and {{export CLASSPATH=}} on Mac OS X, Linux and Unix to remove it.

Q: After I moved my domain classes to a package, they can not be resolved anymore

Normally all Grails artefacts reside in the default package. Java disallows for classes in a (sub-)package to import classes from the default one, and so does Groovy.

Try to move all your classes into packages and don't forget to import them.

Q: How do I check my project into version control / I am getting strange SVN errors with files generated by Grails

Because Grails (certainly up to and including 0.4) generates and copies some files under the project tree, SVN and other version control systems can complain about files changing, or files not being in version control.

For Subversion (SVN) the solution is to mark the correct directories or files to be "ignored". However how you do this is slightly obscure. See the article Checking Projects into SVN.

Q: How do I report a bug, request a new feature, or suggest an improvement to the Grails documentation?

By opening an issue in the Grails issue tracking system. Grails development is managed by a JIRA installation hosted here: http://jira.codehaus.org/browse/GRAILS. You'll need to create an account on the JIRA system before you can create or comment on issues. Opening an issue is often referred to as "raising a JIRA" on the Grails mailing list. Note: it's generally a good idea to consult the Grails mailing list for help before raising a JIRA.

Application Servers

Q: Tomcat errors...

Q: When deploying to my hosting ISP Tomcat, I'm getting an error along the lines of "org.springframework.beans.factory.BeanCreationException" or "org.hibernate.PropertyAccessException: IllegalArgumentException", originally caused by an "java.lang.IllegalArgumentException: object is not an instance of declaring class".

This is caused by a difference in timestamps between files inside your war file and your Tomcat server, and is triggered by timezone differences. After deploying the war, a simple:

cd webapps
find mygrailsappli -exec touch {} ;

and restarting Tomcat will solve the problem. If you can't access the host via a login shell of some sort, then you'll probably need to change the timestamps on your WAR file to match your server before deploying it.

Q: I drop the war file in the Tomcat webapps directory, and nothing happens. I see some Zip file errors in the log.

Try restarting Tomcat.

Q: The war file unpacks okay in Tomcat, but then … nothing. I go to the URL and get a 404 error, no messages in the logs, no nothing.

Grails and Groovy have certain memory requirements.

If memory is not a problem on your server then allocate a large amount of memory, such as 512m (512MB) or more. Also use the server VM option. EG: (-server -Xms512m -Xmx512m). Usually it is better to set both min and max heap size to the same in server applications. What this means is, edit your tomcat5.conf file, and set the option: JAVA_OPTS="-Xms512m -Xmx512m". The tomcat5.conf file is usually in CATALINA_HOME/conf, see the Tomcat website for more information. For more information on what the Java options mean, try calling java -X.

However, if you running on a virtual host with limited memory, Grails 1.0 RC1 has been tested on tomcat 6 with both -Xmx96m and -Xmx128m, it performed well with both settings. I've heard reports of it running on lesser configurations. See: Grails Test On Virtual Server for more information.

Q: I'm getting errors when deploying on JBoss 4.0.x What do I do?

JBoss' unified class loader can cause problems with conflicting Jar files. One issue commonly encountered is with log4j, which is part of both JBoss and Grails. This can be resolved by removing log4j.jar from your deployed .war file or using scoped classloading (with some caveats).

Ideally you wouldn't want to remove the log4j file from your deployment as this requires some additional work and will break many automated deployment/testing processes. JBoss' class loaders are based on a hierarcy of classloaders but this causes issues where there are files shared between the JBoss parent classloaders and the child classloader for our web application. What we really want to do is tell JBoss to leave us alone when it comes across files that we have in our .war file. To do this we must 'scope' our classloader so that the classes we are using are in their own class loader repository away from the JBoss classes. To do this for a war is relatively straightforward. Create a file called jboss-web.xml and place it in your "web-app/WEB-INF" directory (it will be included in the WAR file's "WEB-INF"):

This will tell the JBoss class loaders to isolate (to a large extent) our classes from those that JBoss is using, to load our classes first and not to delegate class loading to the parent classloading in case of a conflict. You need to replace "myappname" with the name of your app or any other string. The only thing you want is for the loader-repository name to be unique. Generally a good string to use will include your package name so you can avoid namespace collisions within the webserver

"com.foocompany.webProjectBar:loader=webProjectFooBar.war"

would be a good name this is almost guaranteed to be unique within the container. This is especially important in a shared hosting environment based on JBoss.
Once you have finished with that file and you drop it into the WEB-INF directory of your web application and you deploy your web application ideally you should be done. But you're not because of one slight miscalculation. Log4J will by default look for a log4j.xml file to load its properties from and failing that, it will fall-back to a log4j.properties. Since we have a classloader hierarchy, you know that if the child classloader fails - the request to load a class (or resource) gets escalated up the classloader chain until a classloader accepts it or until they all fail to load the resource at which time an Exception is thrown. The problem is that the parent classloader already knows about a log4j.xml file - the one loaded by JBoss, so you will find that you still throw a ClassCastException because log4j.xml for JBoss is trying to load log4j for your web application. There are two possible fixes for this:

1) In grails we migrate to the log4j.xml file syntax for specifying log4j settings and the problem goes away because the child classloader will find what its looking for (and this has been suggested and being evaluated)
2) Change the configuration of the JBoss application server so that it doesn't have a log4j.xml file either. :-) If you have the ability to make this change, it make save you some headache down the road with other web applications that bundle log4j in their distributions as well. The fix is very straightforward:

Go in the servers conf directory. I have JBoss installed in /jboss-4.0.5.GA, so the conf directory is /jboss-4.0.5.GA/server/default/conf. If you are deploying into a profile other than default, simply substitute default for the name of the profile that you are deploying into such as /jboss-4.0.5.GA/server/foobarprofile/conf.

Move the log4j.xml to jboss-log4j.xml

Edit the jboss-service.xml file and find the mbean called "org.jboss.logging.Log4JService". Change the attribute "ConfigurationURL" so that it points to this new jboss-log4j.xml file:

<mbean code="org.jboss.logging.Log4jService"
name="jboss.system:type=Log4jService,service=Logging"
xmbean-dd="resource:xmdesc/Log4jService-xmbean.xml"><attribute name="ConfigurationURL">resource:jboss-log4j.xml</attribute>
<!-- Set the org.apache.log4j.helpers.LogLog.setQuiteMode. As of log4j1.2.8
this needs to be set to avoid a possible deadlock on exception at the
appender level. See bug#696819.
-->
<attribute name="Log4jQuietMode">true</attribute>
<!-- How frequently in seconds the ConfigurationURL is checked for changes --><attribute name="RefreshPeriod">60</attribute></mbean>

Q: How do I setup Jetty behind Apache?

Setting up Jetty behind apache is relatively straightforward. Jetty recommends that you utilize mod_proxy and proxy using http, not AJP.

In your Apache install make sure mod_proxy and proxy_http are configured.

Q: How do I setup Grails on Oracle AS?

Q: Deploying on JETTY 6

I had to remove the lib/jsp 2.1 directory from my jetty install to disable JSP 2.1

Q: Deploying under IBM's J9 JVM (applies to WebSphere installs too)

WebSphere uses the J9 Java Virtual Machine. J9 is also one of the alternatives you'll have to consider on a PPC Linux box because the Sun JVM doesn't run there. Unfortunately J9 does a lot of work under the covers to make things run faster that don't work well with Groovy.

We found that sending email caused j9 to throw a GPF Fault - and Tomcat then does it's version of a Core Dump. Perusing the dump file doesn't seem to help - as there is no indication of the class or method which caused GPF. GPF is short for General Protection Fault - which means that something is attempting to access a resource to which they do not have permission (per the underlying operating system). And finally once past the GPF mail wouldn't send due to some incompatiblity with the Gnu JavaMail API and the Sun specification JavaMail API. Once the Gnu mail.jar was replaced with the Sun version - email functioned normally.

2. Add commons-logging-adapters-1.1.jar to the lib directory
3. After adding the application, modify the classloader to "Parent last."
For more information, IBM offers a 20-page PDF document on how to get commons-logging to work with WebSphere. (See also GRAILS-515.)
WebSphere ships with an old version of ant.jar in $WASHOME/lib

You will see errors like 'java.lang.NoSuchMethodError: org.apache.tools.ant.UnknownElement: method setNamespace(Ljava/lang/String;)V not found'.
Workaround: replace the ant.jar with a more recent version of ant (e.g. from GRAILS_HOME/lib).

Acegi filter does not find FilterChainProxy

Class of type org.acegisecurity.util.FilterChainProxy not found in classloader

It seems to be related to a bug in WebSphere that doesn't handle servlet filters properly.
As seen in the Jive support forums, setting the com.ibm.ws.webcontainer.invokefilterscompatibility property to true in Servers > Server > Web Container Settings > Web Container > Custom Properties, may help solve the issue.

Q: WebSphere 5.1 is giving me all sort of troubles, anyone got any luck with it ?

There isn't a crystal-clear procedure for WebSphere 5.1 deployment of grails 1.0.X applications yet. Some of the solutions detailed above are applicable to WebSphere 5.1, but some are relevant to 6.X only.

For more information on a person's own difficulties with this, see Deploying to WebSphere 5.x Journal. Please consider contributing to that page if you make progress on it or if you know the steps for a successful deployment.

Q: I'd like to implement a big project as multi modules with Grails, What to do?

Since version 0.4, Grails has came with a plugin architecture. You can separate your project as a set of plugins. See how to develop a plug-in here.

View Technologies

Q: When I point my browser at a particular page of my application, I get a 404 error that says <something>.jsp could not be found. I am using GSPs, so why is Grails looking for a JSP file that doesn't exist?

When you get this error, Grails has already looked for the appropriate GSP file but not found it. It then looks for a suitable JSP file and if that can not be found, you get the error about the JSP file. So if you are using GSPs and see this error, you need to check that the GSP file is in the right place with the correct name.

Q: Can I view my GSP's (Groovy Server Pages) directly?

A: Yes, GSPs in the 'views' directory are directly accessible. You can prevent direct access to the GSPs by intercepting "/**.gsp" in UrlMappings.groovy

Q: Why won't XXX Javascript Library Display Properly?

A: Sometimes third party javascript libraries depend upon other resources loaded directly from the javascript files themselves like stylesheets. Examples of libraries that do this would be the Yahoo UI libraries and niftycube. When the javascript attempts to load the URL Grails changes the URL so that the resource is not found. Try adding a link using the createLinkTo tag for the particular resource.

Q: What's the difference between fieldValue(bean:instance, field:"id") and instance.id?

is that the latter is sensitive to data binding errors. The point where this is important is when requestInstance had its properties set by data binding from the
request params, and some of the property values failed validation. In that case requestInstance.attr will return the previous value of the property, whereas fieldValue() will return the invalid value (stored in the errors object) that was used for data binding. If you're re-rendering an edit form with the errors highlighted then it's better to use fieldValue, as it allows the user to correct their last edit
rather than losing it and having to start again from the previous valid value.

Controllers

Q: Can I use the render method to return a binary file to the client?

A: Since Grails 2.0.x it's possible to use the method render directly:

Q: How do I get the date from a form submission?

The actual date parameter that is the same as your class (in the sample below, "startDate") is simply a tag that tells grails that it is a struct. To get at the actual date input by the user, you need to look at the individual month, year & day parameters.

The only drawback of this is that Domain class reloading does not work (since the class resides in the src/groovy folder instead of the grails-app/domain folder), but at least it allows you to specify sequences and column names and advanced mappings without having to resort to custom XML mappings.

Q: How can I turn on logging for hibernate in order to see SQL statements, input parameters and output results?

Q: Why are my many-to-many columns backwards?

Security

Q: How can I secure my application?

There are a number of ways to secure your application, a simple way is with a Grails filter.

However, it is recommended that you build your application on one of the excellent security plug-ins for Grails such as the Spring Security 2.0 plug-in or the JSecurity plug-in both which solve a lot of common security patterns (login, registration, roles, permissions etc.)

Grails in Eclipse

Q: Launching Grails in Eclipse fails with an exception about JAVA_HOME

Your Eclipse is configured to use a Java Runtime Environment or JRE. However, to launch a Grails application you need a Java Developer Kit or JDK. If you don't have a JDK installed on your system your can download the latest version from http://java.sun.com

Go to Preference in Eclipse (in the Window menu) and go to "Java/Installed JREs". You will find a JRE installed, for example "jre1.5.0_09". Now add the JDK by clicking the "Add..." button. Click the "Browse..." button and select the location of your JDK (for example "C:Program FilesJavajdk1.5.0_09"). Click "Ok" and enter a name for this JDK (for example "JDK 1.5.0_09").

Now make sure to select the JDK you just installed in your launch configuration.

Misc

Q: How can I access domain classes from sources in src/groovy?

Sometimes, you are developing some utility classes that live in src/groovy and which you intend to use from Services and other artifacts. However, as those classes are pre-compiled by Grails, it is not possible to instantiate them and write things like Book.findByTitle("Groovy in Action"). But fortunately, there is a workaround since it's possible to do this:

Q: Can Groovy work with Terracotta clustering cache?

Sure can. Checkout this great post by Taylor Gautier (an employee at Terracotta).

General Migration to Grails 1.1

Q: Where can I find out about major grails 1.1 migration issues?

http://jira.codehaus.org/browse/GRAILS-3143

Q: Do you still need a GRAILS_HOME env variable? Is this issue maven related only?

If you are using the Grails command line (e.g. "grails compile"), then
you need to set GRAILS_HOME. If you are using Maven or Ant to build
your project, then you don't. Setting the environment variable should
have no effect on Maven builds, but some plugins do use it directly in
their scripts.

If you are having problems with a particular plugin with your Maven
build, then please nag the plugin author, who can then hassle me for
help if he or she so chooses.

Q: I see that the plugins directory is gone. Are there any other project structure differences we should know about?

I've made some progress on section 4 of the documentation, which will
explain some of what has happened. The "plugins" directory has simply
moved. Another significant change is that configuration settings
related to the build (such as where classes are compiled to or what
should be packaged in to a WAR file) go into the new
"grails-app/conf/BuildConfig.groovy" file.

Q: Is the grails testing plugin part of the 1.1 dist?

Yes, and it is no longer a plugin.

Q: I think the join table mapping behavior has changed in 1.1, and there is a new mapping DSL syntax (is this true?). What are the ramifications and best practices for dealing with related issues?

Not going there.

Q: It seems many of the plugins may be broken now when trying to run in grails 1.1. What is the best way to follow up if we find an issue with a plugin, and where can we go to learn ahead of time if a plugin may have problems in 1.1?

I currently recommend sending an e-mail to this list with a subject
along the lines of "Plugin XXX not working with Grails 1.1".