Troubleshooting OMERO

Frequently Asked Questions

If you cannot find what you are looking for here, try the FAQ.

Which user account and password do I use where?

Accounts table, including the example usernames and passwords used in the installation guides:

Account type	Function	Username	Password
System	Administrator/Root
System	(Database) service account	postgres
System	(OMERO) service account	omero_user
Database	Database administrator	postgres
Database	Database user	db_user	db_password
OMERO	OMERO administrator	root	root_password
OMERO	OMERO users

Note

These example usernames and passwords are provided to help you follow the installation guide examples. Do not use root_password or db_password; substitute your own passwords.

There are a total of three types of user accounts: system, database and OMERO accounts.

System accounts

These are accounts on your machine or directory server (e.g. LDAP, Active Directory). One account is used for running the OMERO server (either your own or one you created specially for running OMERO, referred to here as “omero_user”). There is also a user called the “administrator-level user” on the Windows installation page and “root-level user” on the UNIX installation page (which includes Mac OS X). A separate “postgres” user is used for running the database server. The “omero_user” account runs the OMERO 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 privileges in order to use another account to perform particular actions e.g. the “postgres” user to create a database. However the OMERO.server should never be run as the root-level/administrator-level user or as the system-level “postgres” user.

Database accounts

The PostgreSQL database system contains user and administrative accounts; these are completely separate from the system accounts, above, existing only inside the database. The database administrative user (“postgres”) is the owner of all the database resources, and can create new users internal to the database. A single database account is used at run time by OMERO to talk to your database. Therefore, you must configure the “omero.db.***” values during installation:

$ bin/omero config set omero.db.user db_user
$ bin/omero config set omero.db.pass db_password

Note

Do not use db_user or db_password here; substitute your own username and password.

A database user may have the same name as an account on your machine, in which case a password might not be necessary.

OMERO accounts

These accounts only exist inside the OMERO system, and are completely separate from both the system and database accounts, above. 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
Please enter omero.db.version [OMERO5.0]:
Please enter omero.db.patch [0]:
Please enter password for new OMERO root user:       # root_password
Please re-enter password for new OMERO root user:      # root_password
Saving to ~/OMERO5.0__0.sql

Other OMERO users can be created via the OMERO.web admin tool. None of the passwords have to be the same, in fact they should be different unless you are using the LDAP plugin.

Server fails to start

1. Check that you are able to successfully connect to your PostgreSQL installation as outlined on the PostgreSQL page for your OS (Windows PostgreSQL page or UNIX/Mac PostgreSQL page).
2. Check the permissions on your omero.data.dir (/OMERO or C:\OMERO by default) as outlined on the OMERO.server installation page for Unix/Mac users, or the OMERO.server binary repository page for Windows users.
3. Are you on a laptop? If you see an error message mentioning “node master couldn’t be reached”, you may be suffering from a network address swap. Ice does not like to have its network changed as can happen if the server is running on a laptop on wireless. If you lose connectivity to icegridnode, you may have to kill it manually via kill PID or killall icegridnode (under Unix).
4. If you see an error message mentioning “Freeze::DatabaseException” or “could not lock file: var/registry/__Freeze/lock”, your icegrid registry may have become corrupted. This is not a problem, but it will be necessary to stop OMERO and delete the var/master directory (e.g. rm -rf var/master). When restarting OMERO, the registry will be automatically re-created.

Remote clients cannot connect to OMERO installation

The Admin section of OMERO.web appears to work properly and you may or may not have created some users, but no matter what you do remote clients will not speak to OMERO. OMERO.insight gives you an error message similar to the following despite giving the correct username and password:

This is often due to firewall misconfiguration on the machine that runs your OMERO server, affecting the ability of remote clients to locate it. Please see the Server security and firewalls page.

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 your SSH session by using the -x flag as follows before you restart the OMERO.server:

ssh -x my_server.examples.com

OutOfMemoryError / PermGen space errors in OMERO.server logs

Out of memory or permanent generation (PermGen) errors can be caused by many things. You may be asking too much of the server. Or you may require an increase in the maximum Java heap or the 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:
      <option>-Xdebug</option>
      <option>-Xrunjdwp:server=y,transport=dt_socket,address=8787,suspend=n</option>
      -->
      <option>-Xmx512M</option>
      <option>-Djava.awt.headless=true</option>
      <option>-Dlog4j.configuration=${OMERO_ETC}log4j.xml</option>
      …
  

  Replace -Xmx512M initially with -Xmx1024M or greater as required, (use -Xmx1024M -XX:MaxPermSize=128m as an alternative).

Alternatively, if you are finding out of memory errors in one of the other process logs (e.g. Indexer-0.log or PixelData-0.log), look for the entry in etc/grid/templates.xml corresponding to that process and change the -Xmx option there (e.g. under <server-template id="IndexerTemplate"> or <server-template id="PixelDataTemplate">, respectively).

Furthermore, under certain conditions access of images greater than 4GB can be problematic on 32-bit platforms due to certain bugs within the Java Virtual Machine including Bug ID: 4724038. A 64-bit platform for your OMERO.server is HIGHLY recommended.

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.

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"/>

Search does not return expected results

If searching for a specific term does not return the expected results (e.g. searching for the name of a tag does not return the full list of a user’s images annotated with that tag) there are a few things that may have gone wrong.

• Check the server’s log directory for a file named Indexer-0.log and monitor its progress (e.g. using tail or similar). If messages of the format:

  INFO  [   ome.services.fulltext.FullTextIndexer ] (3-thread-2) INDEXED 2 objects in 1 batch(es) [2483 ms.]
  

  are periodically being appended to the log file, then your indexer process may be running behind. You can either wait for it to catch up, or try increasing the search batch size in order to speed processing. See the section on the omero.search.batch setting for more information.

• If there are no updates to the Indexer-0.log file even when new images, tags, files, etc. are added to the server, then it is possible that the Indexer process has become stuck. It is possible to force a restart of the indexer using the IceGrid Tools like so:

  > bin/omero admin ice
  > omero admin ice
  Ice 3.4.2  Copyright 2003-2011 ZeroC, Inc.
  >>> server list
  Blitz-0
  DropBox
  FileServer
  Indexer-0
  ...
  >>> server stop Indexer-0
  

  You do not need to manually re-start the Indexer, as IceGrid will handle the creation of a new Indexer process automatically.

• If the missing search terms are part of a very large text file, it is possible that the file has not been indexed due to exceeding the indexer’s maximum file size limit. See the section on the omero.search.max_file_size setting for more information on increasing this limit.

• If none of the above steps have resolved the situation, it is possible that your search index has become corrupt. If this is the case, you will need to re-index your server’s content. See the section on Re-indexing for more information. Keep in mind that you may also need to adjust the settings for the search batch size, maximum file size, and indexer’s heap size, as outlined above.

OMERO.web issues

OMERO.web is not accessible from remote computer

To configure the out-of-the box setup to listen for webadmin and webclient connections on different host run:

c:\omero_dist> bin/omero web start 'host' 'port'

OMERO.web did not start on the production

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

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

  • LOGDIR

    LOGDIR = '/home/omero/weblog/'
    

• Check if /home/omero/omero_dist/var/lib/custom_settings.py exists.

• Check 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, for example, apache_user:apache_group ownership:

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

OMERO.web piecharts

‘Drive space’ does not generate pie chart or ‘My account’ does not show markup picture and crop the picture options.

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 a few 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 Pillow (packages should be available for your distribution). Also double check if all of the prerequisites were installed from OMERO.web deployment (UNIX instructions or Windows instructions).

Other issues

Connection problems and TCP window scaling on Linux systems

Later versions of the 2.6 Linux kernel, specifically 2.6.17, have TCP window scaling enabled by default. If you are 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

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-1.7.0.0/jre/.systemPrefs/prefs.xml

These warnings (also sometimes listed as ERRORS) can be safely ignored, and are solely related to how Java is installed on your system. See http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4751177 or this ome-users thread on our mailing list for more information.

Too many open files

This is caused by the number of opened files exceeding the limit imposed by your operating system. It might be due to OMERO leaking file descriptors; if you are not using the latest version, please upgrade, since a number of bugs which could cause this behavior have been fixed. It is also possible for buggy scripts which do not properly release resources to cause this to occur. To view the current per-process limit, run

ulimit -Hn

which will show the hard limit for the maximum number of file descriptors (-Sn will show the soft limit). This limit may be increased. On Linux, see /etc/security/limits.conf (global PAM per-user limits configuration); it is also possible to increase the limit in the shell with

ulimit -n newlimit

providing that you are uid 0 (other users can only increase the soft limit up to the hard limit). To view the system limit, run

cat /proc/sys/fs/file-max

On Mac OS X, the standard ulimit will not work properly. There are several different ways of setting the ulimit, depending upon the version of OS X you are using, but the most common are to edit sysctl.conf or launchd.conf to raise the limit. However, note that both of these methods change the defaults for every process on the system, not just for a single user or service.

Increasing the number of available filehandles via ‘ulimit -n’

ValueError: filedescriptor out of range in select() - this is a known issue in Python versions prior to 2.7.0. See #6201 and Python Issue #3392 for more details.