Troubleshoot installation issues

Installation logs

To raise an installation ticket with Support, zip up and attach the following logs:

  • Dimensions server SDP trace.

  • OpenText PulseUno and CM Bridge start up.

  • OpenText Deployment Automation (DA) install.

    For details about installing DA, see Support.

  • Tomcat startup.

Incompatible Schema Version Error

Error Example:

2025/04/28 11:00:02.124000Z  T532 E: Dimensions database "cm_typical" has incompatible schema version 14.7 (required at least 25.x)

Description:

This error occurs when the remote PostgreSQL database schema is older than required.

Use Cases and Resolutions:

Installing Server Only (25.2)

Condition: Remote database schema is 14.x

Solution:

  1. Add the following to %DM_ROOT%\dm.cfg (25.2 installation):

    DM_FORCED_SCHEMA_VERSION 25

  2. Restart the Dimensions CM listener services.

Upgrading from 14.7 to 25.2 (Server Only)

Condition: Remote database schema is 14.x

Solution is same as above:

Set DM_FORCED_SCHEMA_VERSION 25 in %DM_ROOT%\dm.cfg, then restart the listener services.

Dimensions listener

Dimensions CM uses a listener process/service to manage access by clients to the server. If users are unable to connect to CM after an installation, this may be caused by the listener not starting successfully. Follow the procedures below to ensure that connection details are valid, and that the installation is properly configured.

  • Validate that the Dimensions Listener and pool management executables load and run successfully

    To validate that Dimensions CM has been installed correctly and that the executables can run without any issues, log in as the owner of the CM installation, set up the environment, and try to run the following executables from the command prompt: 

    dmlsnr
dmpool
dmappsrv

    If any of these executables fail to run cleanly due to library or DLL loading errors, your installation may have failed to install properly. You need to determine why these loading errors are present before you can successfully run Dimensions CM. Common causes for such errors might be the failure to follow pre-installation requirements (for example, installing the necessary patches), running on a nonsupported operating system, or that the environment is not set up correctly. If none of these appear to be the case and re-installing Dimensions CM does not solve the issue, contact Serena Support.

  • Validate that the log in details used for the Dimensions CM pool are correct

    During the installation process you were prompted for details such as the user to own the Dimensions CM pool. If the details you supplied during installation are incorrect, the Dimensions Listener may fail to start. You can check if these login details are correct by utilizing a set of special initialization parameters that activate tracing of the Dimensions Listener and provide more details as to what the cause of failure might be. For instructions on how to activate this listener tracing, see Enabling Dimensions Listener Tracing in Enable Dimensions listener tracing.

    If the logs generated as a result of enabling the listener trace contain errors such as the ones below, it is possible that either the user name or associated password that you specified during the installation are wrong.

    dmpool 2014/01/23 12:25:55 E P3036 T1204 password not
set for user xxx\dmsys
dmpool 2014/01/23 12:25:55 E P3036 T1204
StartUserProcess failed with 1326, Logon failure:
unknown user name or bad password.
dmpool 2014/01/23 12:25:55 E P3036 T1204 xxx\xxx/
*****, invalid user or password
dmpool 2014/01/23 12:25:55 E P3036 T1204 Cannot
initialize pool
dmpool 2014/01/23 12:25:55 L P3036 T1204 Exiting
or
dmpool 2014/01/23 12:33:26 L P2208 T3648 DBS process
created, id 928
dmpool 2014/01/23 12:33:26 L P2208 T3648 write message
to process 928
dmpool 2014/01/23 12:33:26 L P2208 T3648 read message
from process 928
dmpool 2014/01/23 12:33:26 E P2208 T3648 dmappsrv
initialization failed, process 928
dmpool 2014/01/23 12:33:26 E P2208 T3648 Cannot
initialize pool
dmpool 2014/01/23 12:33:26 L P2208 T3648 Exiting

    You can correct these details as follows:

    The username is specified by the -user parameter in the %installdir%\dfs\listener.dat file (Windows server or agent) or $installdir/dfs/listener.dat file (UNIX agent). If this value is incorrect, edit this file to change the specified user.

    To reset the associated user password used by Dimensions CM, do the following as the administrator of the installation: 

    dmpasswd <username> -del
dmpasswd <username> -add -pwd <newPasswd>

    where:

    • <username> is the operating system user.

    • <newPasswd> is the current password for this user.

  • Validate the system environment and registry entries

    Validate the environment set up from which you are trying to run Dimensions CM. This action is more applicable after an upgrade but the checks are valid for a fresh installation. To check the environment setup:

    • Verify that your installdir variable is pointing to the correct installation and that the executables in the path are the correct ones. You might have earlier versions of executables from previous installations that are being picked up first. Ensure that your path is only picking up one installation of Dimensions CM.

    • Check that your Windows system environment does not have installdir (or PCMS_ROOT) specified. These should only be specified in the Windows registry. If you have PCMSDB, DMDB or LOCAL set in your system environment, verify that they are pointing to the correct values. Do not specify these variables in the system environment unless absolutely necessary.

    • Open your Windows registry hive and navigate to the following key: 

      HKEY_LOCAL_MACHINE/SOFTWARE/Serena/Dimensions

      Under this key you can find entries for each of the versions of Dimensions CM that you have installed on your machine. For the version of Dimensions CM you are trying to run, navigate to that sub-key and verify that the following entries are present and point to the correct locations:

      installdir
DimensionsStart
DimensionsStop

  • Validate that the socket you are using for the listener has not already been allocated or used

    It is possible that the socket service you have chosen for the listener to run on, as specified by the -service parameter in the %installdir%\dfs\listener.dat file (Windows server or agent) or $installdir/dfs/listener.dat file (UNIX agent), is already being used. To validate the socket service:

    1. Check that the -service parameter refers to a valid TCP/IP service name.

    2. Windows only: Check that the socket service number has been specified in the %installdir%/dm.cfg file. The format for this specification is: 

      DM_SERVICE_<SERVICE_NAME>_TCP <serviceNo>

      where:

      • <SERVICE_NAME> is the name of the TCP/IP service.

      • <serviceNo> is the number associated with the socket.

    3. Run the command netstat -a and check the output to determine if the socket you have allocated to Dimensions CM is already being used by another application. If yes repeat the steps above to reset the TCP/IP service number and try again.

    4. If you are using firewalls or other network software/hardware, check that these have been correctly configured to allow communication on your chosen socket/service.

    • Validate that the Windows user has the correct privileges to run Dimensions CM

      Verify that the Windows user running dmpool.exe (by default SYSTEM) has the following Windows operating system privileges to enable them to run the executable:

      • Act as part of the operating system

      • Adjust memory quotas for a process

      • Bypass traverse checking

      • Create a token object

      • Log in as a service

      • Replace a process level token

    • Validate that the License Server is running

      If the listener is running properly, the next step is to validate that the License Server is running, or that the Dimensions CM server is configured to point to a valid license server.

    • Check the user's password

      For the user name that is specified by the -user parameter in the %installdir%\dfs\listener.dat file (Windows server or agent) or $installdir/dfs/listener.dat file (UNIX agent), check that the operating system password for that user contains no underscore ("_") characters. If it does, reset the password using the appropriate operating system commands and through the dmpasswd utility as documented above.

    • Validate the ODBC DSN used for connections

      If you are using ODBC as the Dimensions CM database connection layer, validate that the name of the user specified by the -user parameter in the %installdir%\dfs\listener.dat file (Windows server or agent) or $installdir/dfs/listener.dat file (UNIX agent) is not the same as your DSN name. Failure to do so may cause ODBC connection errors to occur.

    • Check SQL Net authentication errors using Oracle on Windows

      Under certain circumstances you may find that SQL Net (Oracle) fails to authenticate with your pool user. This issue has been seen on various Windows platforms when using Active Directory for user authentication. You can identify this issue by enabling listener tracing. See Enable Dimensions listener tracing. Check the resulting trace logs in the dmappsrv<processId>.log files to see if you have Oracle connection errors. If you have errors, try changing the SQL Net authentication service:

      Edit the contents of the file sqlnet.ora in your %ORACLE_HOME%\NETWORK\ADMIN folder.

      If the file contains the line

      SQLNET.AUTHENTICATION_SERVICES= (NTS)

      change the line to read

      SQLNET.AUTHENTICATION_SERVICES= (none)

      and restart the listener.

    • Remove OPS$ accounts when using Oracle and ODBC

      If the user managing the pool, as defined by the -user parameter in the %installdir%\dfs\listener.dat file (Windows server or agent) or $installdir/dfs/listener.dat file (UNIX agent), has an OPS$ account defined for them in Oracle, this can cause problems with ODBC connectivity.

      To determine if this user has OPS$ privilege, log in as that user and try the following command: 

      sqlplus /

      If a connection to the database is established, run the following SQL commands to drop that OPS$ account. 

      SQL> connect system/<system_passwd>
SQL> drop user OPS$<userId> cascade;

    • Database connection errors

      If none of the suggestions above have helped, the next step is to verify the connection to the database by enabling listener tracing. See Enable Dimensions listener tracing. After attempting to start the listener, look at the output from the log files that are generated. If these log files contain errors similar to the ones shown below, the database details specified by the -dsn parameter in the %installdir%\dfs\listener.dat file (Windows server or agent) or $installdir/dfs/listener.dat file (UNIX agent) are probably incorrect. In the case of the Oracle below, the password details for the database have not been correctly registered:

      dmappsrv 2014/01/23 12:33:26 E P928 T2516 Pcms error:
  1, Error: Unable to connect to database
  "cm_typical"
dmappsrv 2014/01/23 12:36:30 E P3864 T3572 Pcms error:
  1, Error: Schema version check failed for
  Dimensions database "cm_typical"

    To verify that the database connection details are correct, use the RDBMS utilities such as TNSPING (Oracle) to validate that the DSN you specified exists, and that you can connect to it. Also, test the connection to the database specified through the -dsn parameter in the %installdir%\dfs\listener.dat file (Windows server or agent) or $installdir/dfs/listener.dat file (UNIX agent) file, and validate that the connection works.

    If you are running against Oracle, use the Dimensions CM dmdba cpas utility to ensure that the database password for the database you are trying to connect to has been registered against Dimensions CM. Use help cpas within dmdba to ascertain the appropriate options.

    If none of the above solutions help, contact Support for more assistance.