In case of errors or other problems when installing and running LabKey Server, first review installation basics and options linked in the topic:
Install LabKey. This topic provides additional troubleshooting suggestions if the instructions in that topic do not resolve the issue.
Installation Logs
From time to time Administrators may need to review the LabKey Tomcat logs to troubleshoot system startup issues. The LabKey Tomcat logs are located at:
/labkey/apps/tomcat/logs
The logs of interest are catalina.out and labkey.log. catalina.out contains the log file entries from Tomcat as it is starting the LabKey application. Once the LabKey application starts, logging is recorded in labkey.log.
Useful commands:
# monitor the catalina.out log file while LabKey/Tomcat starts
sudo tail -f /usr/local/labkey/apps/tomcat/logs/catalina.out
# monitor the labkey.log file while LabKey/Tomcat starts
sudo tail -f /usr/local/labkey/apps/tomcat/logs/labkey.log
Developer Mode
Running a server in "devmode" provides enhanced logging and enables the
MiniProfiler, and has the server prevent the browser from caching resources like JavaScript and CSS files as aggresively. To run the server in devmode, follow these steps. The
supported version of tomcat will change over time; replace the # in our examples with the actual version number.
- Open a command prompt.
- Go to the <CATALINA_HOME>/bin directory, for example:
C:\labkey\apps\apache\apache-tomcat-#.#.##\bin
- Execute the tomcat#w.exe program:
tomcat#w.exe //ES//LabKeyTomcat#
- The command will open a program window. Click the Java tab.
- In the Java Option box, scroll to the bottom of the properties. Add the following property at the bottom of the list:
- Close the program window and restart the server.
- To confirm that the server is running in devmode:
- Go to (Admin) > Site > Admin Console.
- Under Diagnostics, click System Properties.
- Locate the devmode property, and confirm that its value is 'true'.
Note that the "caching" JVM system property can also be used to control just the caching behavior, without all of the other devmode behaviors. To disallow the normal caching, perhaps because files are being updated directly on the file system, add -Dcaching=false to the JVM arguments.
Diagnostic Information
Which Version of LabKey Server Is Running?
- Find your version number at (Admin) > Site > Admin Console.
- At the top of the Server Information panel, you will see the release version.
Learn more about other diagnostic information on the admin console in this topic:
Common Issues
Conflicting Applications
Before installing LabKey Server, you should shut down all other running applications. If you have problems during the installation, try additionally shutting down any virus scanning application, internet security applications, or other applications that run in the background.
Compatible Component Versions
Confirm that you are using the supported versions of the required components, as detailed in the
Supported Technologies Roadmap. It is possible to have multiple versions of some software, like Java, installed at the same time. Check that LabKey and other applications, such as Tomcat, are configured to use the correct versions.
PostgreSQL Installation
You may need to remove references to Cygwin from your Windows system path before installing LabKey, due to conflicts with the PostgreSQL installer. The PostgreSQL installer also conflicts with some antivirus or firewall software programs. (see
http://wiki.postgresql.org/wiki/Running_%26_Installing_PostgreSQL_On_Native_Windows for more information).
Tomcat Failure to Start
If installation fails to start tomcat (such as with an error like "The specified service already exists."), you may need to manually stop or delete a failing Tomcat service.
To stop the service on Windows, open
Control Panel > Administrative Tools > Services. Select the relevant service, such as
LabKey Server Apache Tomcat #.0 and click
Stop.
To delete, run the following from the command line as an administrator, substituting the major version number for the #:
Connection Pool Size
If your server becomes unresponsive, it could be due to the depletion of available connections to the database. Watch for a
Connection Pool Size of 8, which is the Tomcat connection pool default size and insufficient for a production server. To see the connection pool size for the LabKey data source, select
(Admin) > Site > Admin Console and check the setting of
Connection Pool Size on the
Server Information panel. The connection pool size for every data source is also logged at server startup.
To set the connection pool size, edit your labkey.xml configuration file and change the "maxTotal" setting for your LabKey data source to at least 20. Depending on the number of simultaneous users and the complexity of their requests, your deployment may require a larger connection pool size.
You should also consider changing this setting for external data sources to match the usage you expect. Learn more in this topic:
External Schemas and Data Sources.
Restart Installation from Scratch
If you have encountered prior failed installations, don't have any stored data you need to keep, and want to clean up and start completely from scratch, the following process may be useful:
- Delete the Tomcat service (if it seems to be causing the failure).
- Uninstall PostgresSQL using their uninstaller.
- Control Panel > Programs and Features
- Select PostgreSQL program.
- Click Uninstall.
- Delete the entire LabKey installation directory.
- Install LabKey again.
Installation Forum
You can search for problems resolved through community support in the
LabKey Installation Forum.
If you don't see your issue listed there, you can post a new question. If the install seems successful, it is often helpful to submit
debugging logs for diagnosis.
If the install failed to complete, please include the install.log and install-debug.log from your selected LabKey install directory.
PostgreSQL logs its installation process separately. If PostgreSQL installation/upgrage fails, please locate and include the PostgreSQL install logs as well.
Related Topics
