This topic covers troubleshooting some problems you may encounter building LabKey Server from source.

If you don't find your issue here, try searching the LabKey Developer Forum.

IntelliJ Troubleshooting

IntelliJ Warnings and Errors

  • Warning: Class "org.apache.catalina.startup.Bootstrap" not found in module "LabKey": You may ignore this warning in the Run/Debug Configurations dialog in IntelliJ.
  • Error: Could not find or load main class org.apache.catalina.startup.Bootstrap on OSX (or Linux): you might see this error in the console when attempting to start LabKey server. Update the '-classpath' VM option for your Run/Debug configuration to have Unix (:) path separators, rather than Windows path separators (;).
  • Can't find workspace.template.xml? On older enlistments of LabKey, for example version 15.3, copy <LABKEY_HOME>/server/LabKey.iws.template to LabKey.iws instead.

IntelliJ Slow

You can help IntelliJ run faster by increasing the amount of memory allocated to it. To increase memory:

  • Go to C:\Program Files\JetBrains\IntelliJ IDEA <Version Number>\bin, assuming that your copy of IntelliJ is stored in the default location on a Windows machine.
  • Right click on the idea.exe.vmoptions file and open it in notepad.
  • Edit the first two lines of the file to increase the amount of memory allocated to IntelliJ. For example, on a 2 Gig machine, it is reasonable to increase memory from 32m to 512m. The first two lines of this file then read:
-Xms512m
-Xmx512m
  • Save the file
  • Restart IntelliJ

Server Not Starting Using a LabKey-Provided Run/Debug Configs

Problem: Server does not start in IntelliJ using one of the LabKey-provided Run/Debug configurations. In the console window the following error appears:

/Library/Java/JavaVirtualMachines/jdk1.8.0_40.jdk/Contents/Home/bin/java 
-agentlib:jdwp=transport=dt_socket,address=127.0.0.1:59311,suspend=y,server=n -Dcatalina.base=./
-Dcatalina.home=./ -Djava.io.tmpdir=./temp -Ddevmode=true -ea -Dsun.io.useCanonCaches=false -Xmx1G
-XX:MaxPermSize=160M -classpath "./bin/*;/Applications/IntelliJ IDEA.app/Contents/lib/idea_rt.jar"
-javaagent:/Users/susanh/Library/Caches/IntelliJIdea2016.3/groovyHotSwap/gragent.jar
-Dfile.encoding=UTF-8 org.apache.catalina.startup.Bootstrap start
Connected to the target VM, address: '127.0.0.1:59311', transport: 'socket'
Error: Could not find or load main class org.apache.catalina.startup.Bootstrap
Disconnected from the target VM, address: '127.0.0.1:59311', transport: 'socket'

Cause: This is most likely caused by an incorrect path separator in the Run/Debug configuration's classpath argument.

Solution: Edit the Run/Debug configuration and change the separator to the one appropriate to your platform (semicolon for Windows; colon for Mac/Linux).

Fatal Error in Java Runtime Environment

Error: When starting LabKey or importing data to a new server, you might see a virtual machine crash similar to this:

#
# A fatal error has been detected by the Java Runtime Environment:
#
# SIGSEGV (0xb) at pc=0x0000000000000000, pid=23893, tid=39779
#
# JRE version: Java(TM) SE Runtime Environment (8.0_45-b14) (build 1.8.0_45-b14)
# Java VM: Java HotSpot(TM) 64-Bit Server VM (25.45-b02 mixed mode bsd-amd64 compressed oops)
# Problematic frame:
# C 0x0000000000000000
#
# Failed to write core dump. Core dumps have been disabled. To enable core dumping, try "ulimit -c unlimited" before starting Java again

Cause: These are typically bugs in the Java Virtual Machine itself.

Solution: Ensuring that you are on the latest patched release for your preferred Java version is best practice for avoiding these errors. If you have multiple versions of Java installed, be sure that JAVA_HOME and other configuration is pointing at the correct location. If you are running through the debugger in IntelliJ, check the JDK configuration. Under Project Structure > SDKs check the JDK home path and confirm it points to the newer version.

Gradle task already exists

Error: "task with name ':server:modules:query:antlrSqlBase' already exists"

Cause: A somewhat recent version of IntelliJ has started to put output files in an 'out' directory in each Gradle project's directory (https://youtrack.jetbrains.com/issue/IDEA-175172), so if you run a Gradle build command from IntelliJ these directories will be created. Some of the tasks in LabKey's custom gradlePlugins jar are a little too greedy when looking for input files and will pick up files from this out directory as well.

Solution: This bug for the antlr plugin has been fixed in version 1.1 of the gradlePlugins jar so you can update to that version of the plugins for LabKey 17.2 or later. Also, you can work around this by removing the out directories that Intellij creates and running the build again from the command line.

Cannot find dependencies for compressClientLibs task

Error: "Could not determine the dependencies of task ':server:modules:survey:compressClientLibs'"

Cause: A somewhat recent version of IntelliJ has started to put output files in an 'out' directory in each Gradle project's directory (https://youtrack.jetbrains.com/issue/IDEA-175172), so if you run a Gradle build command from IntelliJ these directories will be created. Some of the tasks in LabKey's custom gradlePlugins jar are a little too greedy when looking for input files and will pick up files from this out directory as well.

Solution: This bug has been fixed in version 1.2 of the gradlePlugins jar, so you can update to that version of the plugins for LabKey 17.2 or later. Also, you can work around this by removing the out directories that Intellij creates and running the build again from the command line.

Cannot find class X when hot-swapping

Cause: IntelliJ puts its build output files, which it uses when doing hot-swapping, in different directories than the command-line Gradle build does, so if you have not built the entire project (or at least the jars that the file you are attempting to swap in depends on) within IntelliJ, IntelliJ will not find them.

Solution: Open the Gradle window in IntelliJ and run the root-level "build" task from that window.

Gradle Troubleshooting

Understanding how gradle builds the server, and the relationships between building and cleaning can help you diagnose many build problems. See these related topics:

Update version of gradlePlugins

We maintain release notes for the gradlePlugins that describe changes and bug fixes to the plugins. Check these notes to find out if the problem you are having has already been addressed. Be sure to pay attention to the "Earliest compatible LabKey version" indicated with each release to know if it is compatible with your current LabKey version. If you want to update to a new version of the gradle plugins to pick up a change, you need only update the gradlePluginsVersion property in the root-level gradle.properties file:

gradlePluginsVersion=1.3.2

Gradle Sync

Problem: Gradle Sync in IntelliJ has no effect on project structure after the settings.gradle file is updated.

Cause: Name conflict between the gel_test project and the gel_test IntelliJ module that would be created from the gel project’s ‘test’ source set. (IDEA-168284)

Workarounds: Do one of the following

Remove gel_test from the test of projects you are including in your settings.gradle file and then do the Gradle Sync. Within IntelliJ do the following Preferences -> Build, Execution, Deployment -> Build Tools -> Gradle Uncheck the setting “Create separate module per source set” Click “OK” Do the Gradle Sync in the Gradle window Preferences -> Build, Execution, Deployment -> Build Tools -> Gradle Check the setting “Create separate module per source set” Click “OK” Do the Gradle Sync in the Gradle window

Log4j

Problem: The server seems to have started fine, but there are no log message in the console after server start up.

Cause: The log4j.xml file that controls where messages are logged does not contain the appropriate appender to tell it to log to the console. This appender is added when you deploy the application in development mode (as a consequence of running the deployApp command). If, for some reason, the file build/deploy/modules/labkeyWebapp/WEB=INF/classes/log4j.xml has been created without the <appender-ref ref="CONSOLE"/> element in the <root> element at the bottom of the file, the log messages will not be sent to the console. For gradlePlugin versions 1.2.2 and earlier, there is a bug in the configureLog4j task that copies and modifies the log4j.xml file such that it will fail to update the deployed version of the file in certain cases.

Workaround: For gradlePlugin versions 1.2.2 and earlier, you will need to make a modification to the <LABKEY_HOME>/webapps/log4j.xml file (e.g., adding a comment to the file) and then run the ./gradlew deployApp command. (The modification is needed so Gradle will understand that the source file has changed. It does not base this off of the timestamp of the file.)

Starting Over with Gradle + IntelliJ

If you get into a situation where the IntelliJ configuration has been corrupted or created in a way that is incompatible with what we expect (which can happen if, for example, you say 'Yes' when IntelliJ asks if you want to have it link an unlinked Gradle project), these are the steps you can follow to start over with a clean setup for Gradle + IntelliJ:

  • Shut down IntelliJ.
  • Revert the <LABKEY_HOME>/.idea/gradle.xml file to the version checked in to VCS.
  • Remove the <LABKEY_HOME>/.idea/modules directory.
  • Remove the <LABKEY_HOME>/.idea/modules.xml file.
  • Start up IntelliJ.
  • Open the Gradle window (View > Tool Windows > Gradle) and click the Refresh icon, as described above.
This may also be required if the version of LabKey has been updated in your current enlistment but you find that your IntelliJ project still refers to jar files created with a previous version.

Tomcat

Tomcat Fails to Start

If Tomcat fails to start successfully, check the steps above to ensure that you have configured your JDK and development environment correctly. Some common errors you may encounter include:

org.postgresql.util.PSQLException: FATAL: password authentication failed for user "<username>" or java.sql.SQLException: Login failed for user '<username>'

These error occurs when the database user name or password is incorrect. If you provided the wrong user name or password in the .properties file that you configured above, LabKey will not be able to connect to the database. Check that you can log into the database server with the credentials that you are providing in this file.

java.net.BindException: Address already in use: JVM_Bind:<port x>:

This error occurs when another instance of Tomcat or another application is running on the same port. Specifically, possible causes include:

  • Tomcat is already running under IntelliJ.
  • Tomcat is running as a service.
  • Microsoft Internet Information Services (IIS) is running on the same port.
  • Another application is running on the same port.
In any case, the solution is to ensure that your development instance of Tomcat is running on a free port. You can do this in one of the following ways:
  • Shut down the instance of Tomcat or the application that is running on the same port.
  • Change the port for the other instance or application.
  • Edit the Tomcat server.xml file to specify a different port for your development installation of Tomcat.
java.lang.NoClassDefFoundError: com/intellij/rt/execution/application/AppMain:
or
Error: Could not find or load main class com.intellij.rt.execution.application.AppMain:

In certain developer configurations, you will need to add an IntelliJ utility JAR file to your classpath.

  • Edit the Debug Configuration in IntelliJ.
  • Under the "VM Options" section, find the "-classpath" argument.
  • Find your IntelliJ installation. On Windows machines, this is typically "C:\Program Files\JetBrains\IntelliJ IDEA <Version Number>" or similar. On Mac OSX, this is typically "/Applications/IntelliJ IDEA <Version Number>.app" or similar.
  • The required JAR file is in the IntelliJ installation directory, and is ./lib/idea_rt.jar. Add it to the -classpath argument value, separating it from the other values with a ":" on OSX and a ";" on Windows.
  • Save your edits and start Tomcat.

Database State Troubleshooting

If you build the LabKey source yourself from the source tree, you may need to periodically delete and recreate your LabKey database. The daily drops often include SQL scripts that modify the data and schema of your database.

Database Passwords Not Working

Problem: My passwords to PostgreSQL and MS SQL Server aren't working.

Solution: Unlike Ant, the Gradle build system will automatically escape any special XML characters, such as quotes and ampersand symbols in the pg.properties / mssql.properties files. When migrating these files from Ant to Gradle, replace any escaped ampersands (&amp;) with plain text ampersands (&).

Environment Variables Troubleshooting

JAVA_TOOL_OPTIONS

Most users will not have this problem. However, if you see a build error something like the following:

error: unmappable character for encoding ASCII

then setting this environment variable may fix the problem

export JAVA_TOOL_OPTIONS=-Dfile.encoding=UTF8

Ext Libraries

Problem: Ext4 is not defined.

The page or a portion of the page is not rendering appropriately. Upon opening the browser console you see an error stating "Ext4 is not defined". This usually occurs due to a page not appropriately declaring client-side code dependencies.

Example of the error as seen in Chrome console.

Solution

Declare a dependency on the code/libraries you make use of on your pages. Depending on the mechanism you use for implementing your page/webpart we provide different hooks to help ensure dependent code is available on the page.

  • Wiki: In a wiki you can use LABKEY.requiresScript() with a callback.
  • File-based module view: It is recommended that you use file-scoped dependencies by declaring a view.xml and using the <dependencies> attribute.
  • Java: In Java you can use ClientDependency.fromPath(String p) to declare dependencies for your view. Note, be sure to declare these before the view is handed off to rendering otherwise your dependency will not be respected.
  • JSP: Override JspBase.addClientDependencies(ClientDependencies dependencies) in the .jsp. Here is an example.
Background: In the 17.3 release we were able to move away from ExtJS 4.x for rendering menus. This was the last “site-wide” dependency we had on ExtJS, however, we still continue to use it throughout the server in different views, reports, and dialogs. To manage these usages we use our dependency framework to ensure the correct resources are on the page. The framework provides a variety of mechanisms for module-based views, JavaServer Pages, and Java.

Related Topics

Discussion

Was this content helpful?

Log in or register an account to provide feedback


previousnext
 
expand all collapse all