From OpenKM Documentation
Jump to: navigation, search


This is a compilation of the most common OpenKM user problems and their solutions. If you have any other problem not listed here, please take a look at to be helped by our community. Also you can request professional support at

Can't access OpenKM from other computers

By default, JBoss only listens for connections on localhost. If you want to access OpenKM from other computers, you need to start JBoss passing the parameter -b


./bin/ -b 


\bin\run.bat -b

Other options

./bin/ -Djboss.bind.address=

Error downloading document as PDF

Code: OKM-004006
Message: conversion failed: could not save output document; OOo errorCode: 2074

This error occurs when you want to download a document as PDF and there is some error with Perhaps the installation has some missing components. Try to install these packages:

$ aptitude install openoffice.org2-l10n-es
Code: OKM-004013
Message: connection failed: socket,host=localhost,port=8100, Connection refused'

This error occurs when you want to download a document as PDF and there is some error with the connection. Perhaps there is no running in server mode (headless). See Third-party software integration: for more info.

OpenKM not deployed due to a webservice error

Perhaps your computer doesn't have Internet access? JBoss tries to validate WSDL descriptors on application deployment, can't access DTD and throws an exception. This is a known JBoss issue. More on JBoss webservices at

A workaround is disabling webservices in OpenKM:

  • Stop JBoss.
  • Delete the folder $JBOSS_HOME/server/default/deploy/OpenKM.ear/OpenKM.war/WEB-INF/classes/es/git/openkm/ws.
  • Start JBoss again.

It should solve the deployment problem. If the EAR is not exploded you can browse it with Midnight Commander (on Linux) or WinRAR (on Windows).

Error when click on "Copy to clipboard"

To enable JavaScript "Copy to clipboard" buttons on Firefox and Mozilla, enter the following line into browser address bar: "about:config"

The list of preferences should open in browser window. Right-click somewhere in the active part of preference list window and choose New > Boolean option from context menu. Paste the following Preference name into the New boolean value window input box: "signed.applets.codebase_principal_support"

Error opening contextual menu - right click on firefox"

I right-click on a document, but OpenKM contextual menu is hidden by the browser. If you use Firefox, go to Edit → Preferences → Content, check "Active JavaScript", click on "Advanced" and check "Deactivate or replace contextual menus" option.

The Administration tab is empty

This is a known bug of Internet Explorer. Switch to Firefox: its JavaScript engine also is faster, so your OpenKM experience will be better. Or access it from Tools → Show administration. Or point your browser to http://localhost/OpenKM/es.git.openkm.backend.Main/.

IMAP SSL certificate error

First obtained my certificate with the openssl command and after this import the certificate with:

keytool -import -alias -keystore /etc/java-6-sun/security/cacerts -file imapd.pem

You have to restart JBoss to refresh the SSL certificates. See also:

Unable to run Scanner applet under Linux

If you enable the Java Console and see this error:

java.lang.UnsatisfiedLinkError: Could not find library []

You have to install the libsane-dev package:

$ sudo aptitude install libsane-dev

Some PDF file not shown in preview

Perhaps the PDF is copy protected. Hence, you're not allowed to convert it.

FATAL   PDF disallows copying

If you created this PDF using Acrobat Distiller, try switching the copy protection checkbox off. If you can't disable the protection you can modify the 'pdf2swf source code to disable this check (see

Other problems may be due to complex PDF documents.

ERROR This file is too complex to render- SWF only supports 65536 shapes at once

You can invoke the pdf2swf utility with the -s poly2bitmap option. The generated document quality is worse, but you can see it at least. This can be simplified to be used by OpenKM in the preview generation. Create a script called

/usr/bin/pdf2swf -s poly2bitmap $*

Make it executable:

$ chmod +x

And don't forget to change the OpenKM.cfg file:


Or set in the administration depending on your OpenKM version:


See SWFTools for more info.

Random errors in preview

We have detected errors especially with Firefox under Linux, because the Flash plugin is quite old or you have installed the GNASH flash plugin and not the original one from Adobe. To fix this, install the "Flash Aid" plugin under Firefox and run the wizard. It will install the right Flash Plugin version into your preferred browser.

Export to zip file gives wrong charset

This issue is corrected since OpenKM 4.1-RC2 and exported zip archives should be opened without problems from WinZip 14 or higher. But you may have an issue in Ubuntu Linux. The problem is the unzip package, which should be compiled with a patch to enable UTF-8 chars in file names. You can find a patched unzip for Ubuntu/Debian at To keep informed about the progress in this issue, go to Bug #10979: unzip does not support UTF-8 filenames.

Also you can try to install the port of the 7-Zip compression tool for Linux:

$ sudo aptitude install p7zip-full

Jackrabbit: Bad check digit

If you have a problem like this when starting OpenKM

2010-06-03 17:56:14,640 ERROR [org.apache.jackrabbit.webdav.simple.DavResourceImpl] Error while importing resource: cannot read item dd85e9b7-6398-4720-a00d-87374467e4f9
2010-06-03 17:56:14,640 WARN  [org.apache.jackrabbit.core.lock.LockManagerImpl] Bad lock token: Bad check digit.

Probably you have a problem with the crappy LVM setup that was responsible for this problem. Fresh installation could solve the problem!

Take a look at forum post at

Errors caused by proxy configuration / Error OKM-009006

If you've configured OpenKM under a proxy, sometimes it's necessary to set JBoss params to indicate it, because there could be some connection errors in rpc calls.

-Dhttp.proxyHost=x.x.x.x -Dhttp.proxyPort=yyyy

Microsoft Office Addin disappears after restarting Office

Could be a problem with default template ( ). To solve it:

  • Open
  • Go to menu tools / personalize / Tool bars
  • Open OpenKM toolbar
  • Save

OpenKM server has no direct Internet connection

If you need a proxy to access the Internet, edit your /etc/bash.bashrc file as root and put these lines at the end of your /etc/bash.bashrc file :

export http_proxy=
export ftp_proxy=

You can omit the username:password, if your proxy server has no password.

But maybe the server can't access the Internet at all. In this case you will have problems when validating $JBOSS_HOME/PropertyGroups.xml. Read Property Groups definition to see the solution. Also edit OpenKM.cfg and set:

Access denied installing OpenKM as service on Windows 7

The command shell works slightly differently in Vista. By default when you run cmd.exe, it does not give administrator rights. To get around it, create a shortcut to cmd.exe on desktop, open Properties, Compatibility tab and check box for Administrator rights. Then you can do admin stuff on cmd line. More information here Configure JBoss service

Problems with character encodings

If your language has non-ASCII characters and they are displayed as garbage you have a problem with encodings. To solve this, you have to edit the JBoss start script.

Nota advertencia.png This process, as described here will destroy the OpenKM database and will create a new one. Be careful! If you want a non-destructive way of achieving this, you need to delete actual inserted translations and insert them again.

In the case of Linux, edit the file $JBOSS_HOME/bin/ and replace the line:

 JAVA_OPTS="-Xms256m -Xmx2048m -XX:PermSize=128m -XX:MaxPermSize=256m"

With this one:

 JAVA_OPTS="-Xms256m -Xmx2048m -XX:PermSize=128m -XX:MaxPermSize=256m -Dfile.encoding=utf-8"

In the case of Windows, edit the file $JBOSS_HOME/bin/run.bat and replace the line:


With this one:

 set JAVA_OPTS=%JAVA_OPTS% -Dfile.encoding=utf-8

You need to stop JBoss, delete the $JBOSS_HOME/server/default/data/hypersonic folder and start JBoss again. Now the OpenKM database will be created again and the language translation will be imported right.

Checking error "Document name is different"

This is a known error in Internet Explorer family. To disable name mismatch check, take a look at Disable document name mismatch check.

Error dowloading files under IE with https / SSL

There's a very old bug from version 5.5 until now that seems like Microsoft has not decided to fix , that causes a problem downloading files with IE behind SSL protocol ( the force may be with you, hope some day they will decide to fix it).

The problem is caused by "Cache-control: no-cache HTTP header to the response message", obviously that's valid for any browser except IE family ... other Microsoft IE hidden feature ?

Can see some supporting and forum information about it:

The solution is to change a couple of entries in the Windows Registry:

  • Create a file called ss_download_patch.reg
  • Copy the contents
[HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Internet Settings]
  • Execute it (will be imported into Windows Registry)
  • Then you need to restart Windows for this to take effect.

Nota clasica.png This IE bug has been fixed in OpenKM 5.1.8 (nightbuild from 6 Oct 2011).

Error in uploader / scanner applet

To provide more complete information in order to determine the issue, please activate the Java Console. Read How do I enable and view the Java Console? for more info.

PermGen errors

If you see this error when executing OpenKM:

java.lang.OutOfMemoryError: PermGen space

Edit your $JBOSS_HOME/bin/ (or $JBOSS_HOME/bin/run.bat if using Windows) and set the JAVA_OPTS variable to this value:

JAVA_OPTS="-Xms256m -Xmx2048m -XX:PermSize=128m -XX:MaxPermSize=256m"

See also Presenting the Permanent Generation.

LDAP - Sizelimit exceeded

Caused because bindDN has size limit for each ldap query.

In Openldap The solution is set to bindDN a grat limit, for example ( to change size limit to user used by openkm ldap connection )

limits dn.exact="cn=reader,ou=accounts,ou=admins,dc=example,dc=com" size=100000

See also OpenLDAP Limits.

Behind IIS proxy you get error 404 or 404.15

Using IIS as a web server by default it has a limit for the query string sent to the server if limit is passed then you get some error screen on the client side:

Iis limi1.png

on the server side we get a more detailed error:

Iis limi2.png

To solve this issue we need to increase the maximum size of the query string on the web server:

  • Open Internet Information Services (IIS) Manager
  • In the Connections pane, go to the connection, site, application, or directory for which you want to modify your request filtering settings.
  • In the Home pane, double-click Request Filtering.

Iis limi3.png

  • Click Edit Feature Settings... in the Actions pane.

Iis limi4.png

  • Change the maximum query string length

Iis limi5.png

More information at OpenKM forum

IIS gets IOException: Internal Server Error while uploading file

  • Go to webapps folder
  • Edit the web.config file and add the following under <configuration> where "2097151" is the maximum allowed in IIS
   <httpRuntime maxRequestLength="2097151" />
  • if there is no web.config then just create one from text file & add the following
   <httpRuntime maxRequestLength="2097151" />

Slow login with LDAP

Sometimes there's problem by OS to resolve some LDAP DNS, for it is good practice add in hosts files ( /etc/hosts for linux or C:/Windows/system32/driver/etc/hosts for windows ).

Example based with active directory ( ldap ) with distinguished base name dc=fw,dc=local and server at SBSSERVER domain server name. fw.local SBSSERVER SBSSERVER.fw.local Schema.Configuration.fw.local Configuration.fw.local DomainDnsZones.fw.local ForestDnsZones.fw.local

More information at OpenKM forum

OpenOffice is not starting on Windows

Sometimes is quite difficult to get OpenKM with soffice service started for several and strange reason which depends on your OS Windows version and other specific configuration done in server. That wants to be a minimal guide - check list - to solve it. These steps has sense when you're sure the soffice path is right configured on administration parameters

First ensure you got none openoffice or soffice instance running. If there're something on execution openkm will not be able to start soffice service. Take a look at windows process looking for some openoffice or soffice process running you can use windows process task or some more good tool like Process Explorer tool.

Stop firewall and other possible tools which be able to do not allow start soffice service. For example antivirus or similar.

Try start openkm with adminitrator user from console with command:

catalina.bat run

Nota clasica.png Command must be executed in %TOMCAT_HOME%\bin

Other option is open console with administrator grants. In some Windows OS appears a checkbox to execute with some restrictions. We suggest try both options, we've observate in some cases execute with some restrictions goes right and not the case without any restriction.

Sigar java.lang.UnsatisfiedLinkError Known issue in Windows

If you got openoffice or libreoffice configured will get some error when OpenKM try start as service, to solve it edit your general environment variable PATH and add your tomcat\lib\sigar\ folder, for example like PATH=...;C:\tomcat-7.0.27\lib\sigar

Caused by: java.lang.UnsatisfiedLinkError: org.hyperic.sigar.Sigar.getSigNum(Ljava/lang/String;)I
	at org.hyperic.sigar.Sigar.getSigNum(Native Method)
	at org.hyperic.sigar.Sigar.kill(

WARN net.sf.ehcache.hibernate.strategy.AbstractReadWriteEhcacheAccessStrategy

If you see this message:

 A soft-locked cache entry was expired by the underlying Ehcache.
 If this happens regularly you should consider increasing the cache timeouts and/or capacity limit

Are you experiencing any performance or usability problems as a result of this warning? If not then it seems like you should treat this warning as just that: a warning.

Otherwise, it looks like the solution is to increase the size of maxElementsInMemory to account for the difference in what is cached versus what is realistically being used.

Zoho with SSL connection fails

To use Zoho integration you have to configure your server to deliver the whole certificate chain by itself, because the Zoho client does not looks for the chain. Our solution is reconfigure APR in Tomcat to deliver the CA chain separatly to the server certificate.

It looks like this:

<!-- Define a SSL HTTP/1.1 Connector on port 8443
        This connector uses the JSSE configuration, when using APR, the
        connector should be using the OpenSSL style configuration
        described in the APR documentation -->
   <Connector port="8443" address="" protocol="HTTP/1.1" SSLEnabled="true"
              maxThreads="150" scheme="https" secure="true" acceptCount="100"
           enableLookups="false" clientAuth="true" sslProtocol="SSLv3"

More information at Forum

CMIS bad url behing nginx proxy

location /OpenKM/ {
 proxy_redirect off;
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

More information at Forum