Personal tools
  • We're Hiring!

You are here: Home Documentation OMERO v4.2.2 Troubleshooting


Troubleshooting an OMERO Installation


If you can't find what you are looking for here, you might also peruse the FAQ.

Known Operating System issues

  • Gentoo requires a special patch for compiling Ice (link requested)
  • Ubuntu 08.04 has issues with older Ice packages (ome-users thread)
  • OpenSuSE 10.1 has issues with Python 2.4/2.5 and Ice (ome-users thread)

Which password do I use where?

There are a total of three types of user accounts which are important during the installation process.

  • The first type includes accounts on your machine. There is one regular account (either your own or one you created specially for running OMERO, we'll call it "omero" here); there is the user called a "root-level user" on the Unix installation page (which includes Mac OS X) and "administrator-level user" on the Windows installation page; and there may be a special "postgres" user who controls the database server. The regular "omero" account runs the server, and owns the files uploaded to OMERO. This account must have permission to write to the /OMERO/ binary repository. Some operations in the install scripts require the root-level/administrator-level user in order to become another user like "postgres" to perform particular operations (E.g. create database). However the server should never be run as the root-level/administrator-level user or as the database-owner.

  • The second type of account is the database account. The database-owner ("postgres") can create users completely separate from the accounts on your machine. (Though confusingly, the database-user may have the same name as an account on your machine, in which case a password might not be necessary.) A single database account is used at run time by OMERO to talk to your database. Therefore you have to configure the "omero.db.*" values during installation.

    bin/omero config set omero.db.user omero
    bin/omero config set omero.db.pass secret
  • The last type of account are OMERO accounts. The first user which you will need to configure is the "root" OMERO user (different from any root-level Unix account). This is done by setting the password in the database script:

    bin/omero db script

Other OMERO users can be created via the web admin tool. In no case, do any of the passwords have to be the same (or should they unless you are using the LDAP plugin...)

OutOfMemoryError / PermGen space errors in OMERO.server logs

Out of memory or permanent generation (PermGen) errors can be caused by many things. Fundamentally you may be asking too much of the server and require and increase of the maximum Java heap or permanent generation space. This can be done by modifying the IceGrid configuration for your OMERO.server as follows:

  • In etc/grid/templates.xml:

    <server-template id="BlitzTemplate">
      <parameter name="index"/>
      <parameter name="config" default="default"/>
      <server id="Blitz-${index}" exe="java" activation="always" pwd="${OMERO_HOME}">
        Debugging options:

    Replace -Xmx512M with -Xmx1024M, -Xmx1024M -XX:MaxPermSize=128m or greater as required.

SocketException: Network is unreachable errors in your OMERO.server log on Debian

This is a Debian specific bug.

Quick fix for users hit by this:

    sudo sed -i 's/net.ipv6.bindv6only\ =\ 1/net.ipv6.bindv6only\ =\ 0/' \
    /etc/sysctl.d/bindv6only.conf && sudo invoke-rc.d procps restart

There is an OMERO forum post for comments on the issue.

Import error when running bin/omero ...

    Traceback (most recent call last):
    File "bin/omero", line 67, in ?
        import omero.cli
    ImportError: No module named omero.cli

If you get any import related errors while running bin/omero, the most likely cause is that your PYTHONPATH is not properly set.

  • If you installed Ice globally via your package manager, make sure you included ice-python

  • If you installed Ice manually, e.g. under /opt/Ice-3.3.1 you need to add /opt/Ice-3.3.1/python (or similar) to your PYTHONPATH environment variable. See the Ice installation instructions for more information.

Remote clients can't connect to my OMERO installation!

The OMERO WebAdmin appears to work fine and you may or may not have created some users but no matter what you do remote clients won't speak to OMERO. OMERO.insight gives you an error message similar to the following (and you know that you've put the correct username and password into the OMERO.insight dialog):

Login failure

This often because of firewall misconfiguration on the machine that runs your OMERO server which affects the ability of remote clients to locate it. Please see the OMERO security page.

Server fails to start

  1. Check that you are able to successfully connect to your PostgreSQL installation as outlined on the PostgreSQL page.
  2. Check the permissions on your (/OMERO by default) as outlined on the OMERO Install page, in the ''Pre-Installation'' section.

Connection Problems and TCP Window Scaling

Later versions of the 2.6 Linux kernel, specifically 2.6.17, have TCP window scaling enabled by default. If you're having initial logins never timeout or problems with connectivity in general you can try turning the feature off as follows:

# echo 0 > /proc/sys/net/ipv4/tcp_window_scaling

You can read more about the problems surrounding TCP window scaling here.

My Server Crashes With...

  • X11 connection rejected because of wrong authentication
  • X connection to localhost:10.0 broken (explicit kill or server shutdown).

OMERO uses image scaling and processing techniques that may be interfered with when used with SSH X11-forwarding. You should disable SSH X11-forwarding in the SSH session you will use to start OMERO.server by using the -x flag as follows:

ssh -x

Server or clients print "WARNING: Prefs file removed in background..."

Nov 12, 2008 3:02:50 PM java.util.prefs.FileSystemPreferences$7 run
WARNING: Prefs file removed in background /root/.java/.userPrefs/prefs.xml
Nov 12, 2008 3:02:50 PM java.util.prefs.FileSystemPreferences$7 run
WARNING: Prefs file removed in background /usr/lib/jvm/java-1.7.0-icedtea-

These warnings (also sometimes listed as ERRORS) can be safely ignored, and are solely related to how Java is installed on your system. See or perhaps this thread on our mailing list for more information.

DropBox fails to start: Failed to get session

If the main server starts but DropBox fails with the following entry in var/log/DropBox.log,

2011-06-07 03:42:56,775 ERROR [                        fsclient.DropBox] (MainThread) Failed to get Session:

then it may be that the server is taking a relatively long time to start.

A solution to this is to increase the number of retries and/or the period (seconds) between retries in etc/grid/templates.xml

<property name="omero.fs.maxRetries"  value="5"/>
<property name="omero.fs.retryInterval"  value="3"/>

OMERO.web and "ImportError: No module named rtypes."

To avoid that error please change the following in your

import os.path
import sys
import datetime
import logging

import omero
import omero.clients

OMERO.web is not accessible from remote computer.

  • If you require to configure the out of the box setup to listen for webadmin and webclient connections on different host run by:

    c:\omero_dist> bin/omero web start 'host' 'port'
    Starting django development webserver... 
    Validating models...
    0 errors found
    Django version 1.1.1, using settings 'omeroweb.settings'
    Development server is running at http://host:port/
    Quit the server with CONTROL-C.

OMERO.web did not start on the production.

The user opening OMEROweb.log files needs write permissions to the directory containing the logs file. So, bee sure you have a "log" directory with the correct ownership and correct path set in LOGDIR matches log directory.

  • In your /home/omero/omero_dist/var/lib/ directory add the following to your file:

    • LOGDIR

      LOGDIR = '/home/omero/weblog/'
  • Checking if /home/omero/omero_dist/var/lib/ exist.

  • Checking who owns the log directory and log files:

    $ ls -al /home/omero/weblog/
    total 49
    drwxr-xr-x  2 apache apache   120 Mar 31 11:29 .
    drwxr-xr-x 10 apache apache   520 Mar 31 11:29 ..
    -rw-r--r--  1 apache apache 23766 Mar 31 11:41 OMEROweb.log
    -rw-r--r--  1 apache apache 23978 Mar 31 11:41 OMEROweb.log.2009-03-31
  • or create log and database directories with apache_user:apache_group ownership or another who you want to run with:

    mkdir /home/omero/weblog
    chown apache_user:apache_group /home/omero/weblog

OMERO.web 'Drive space' does not generate pie chart/'My account' does not show markup picture and crop the picture.

Error message says: 'Piechart could not be displayed. Please check log file to solve the problem'. Please check var/log/OMEROweb.log for more details. There are few already known possibilities:

  • 'TclError: no display name and no $DISPLAY environment variable'. Turn off the compilation of TCL support in matplotlib.
  • 'ImportError: No module named Image'. Install Python Imaging Library - packages should be available for your distribution from here. Also double check if all of the prerequisites were installed from here

Mod_python error: "PythonHandler django.core.handlers.modpython"

Double check if apache_user has enough permissions to: '/home/omero/omero_dir/lib/python/', '/home/omero/omero_dir/lib/python/django', '/home/omero/omero_dir/lib/python/omeroweb', '/home/omero/omero_dir/var/lib'.

Document Actions