The server will not start
If the server does not start, then there are a number of potential causes.
The server or other administrative tool is already running
Only a single instance of the server can run at any time from the same installation root. If an instance is already running, then subsequent attempts to start the server will fail. Similarly, some other administrative operations can also prevent the server from being started. In such cases, the attempt to start the server should fail with a message like the following:
{pingauthorize} Server could not acquire an exclusive lock on file
/{pingauthorize}/locks/server.lock: The exclusive lock requested for file
/{pingauthorize}/locks/server.lock was not granted, which indicates
that another process already holds a shared or exclusive lock on that
file. This generally means that another instance of this server is already
runningIf the server is not running (and is not in the process of starting up or shutting down), and there are no other tools running that could prevent the server from being started, and the server still believes that it is running, then it is possible that a previously held lock was not properly released. In that case, you can try removing all of the files in the locks directory before attempting to start the server.
|
If you wish to have multiple instances running at the same time on the same system, then you should create a completely separate installation in another location on the file system. |
There is not enough memory available
When the server is started, the JVM attempts to allocate all memory that it has been configured to use. If there is not enough free memory available on the system, then the server generates an error message that indicates that the server could not be started with the specified set of arguments.
|
It’s possible that an invalid option was provided to the JVM (as described in the following potential causes), but if that same set of JVM arguments has already been used successfully to run the server, then it is more likely that the system does not have enough memory available. |
There are a number of potential causes for this issue:
-
If the amount of memory in the underlying system has changed (for example, system memory has been removed, or the server is running in a zone, or other type of virtualized container, and a change has been made to the amount of memory that container is allowed to use), then the server might need to be re-configured to use a smaller amount of memory than had been previously configured.
-
Another process running on the system is consuming a significant amount of memory, so that there is not enough free memory available to start the server. If this is the case, then either terminate the other process to make more memory available for the server, or reconfigure the server to reduce the amount of memory that it attempts to use.
-
The server was just shut down and an attempt was made to immediately restart it. In some cases, if the server is configured to use a significant amount of memory, then it can take a few seconds for all of the memory that had been in use by the server, when it was previously running, to be released back to the operating system. In that case, run the
vmstatcommand and wait until the amount of free memory stops growing before attempting to restart the server. -
If the system is configured with one or more memory-backed file systems, verify whether any large files might be consuming a significant amount of memory in any of those locations. If so, remove them or relocate them to a disk-based file system.
-
For Linux systems only, there could be a mismatch between the huge pages setting for the JVM and the huge pages reserved in the operating system.
|
If nothing else works, and there is still not enough free memory to allow the JVM to start, then as a last resort, try rebooting the system. |
An invalid Java Environment or JVM option was used
If an attempt to start the server fails with an error message indicating that no valid Java environment could be found, or indicates that the Java environment could not be started with the configured set of options, then you should first ensure that enough memory is available on the system as described previously. If there is a sufficient amount of memory available, then other causes for this error can include the following:
-
The Java installation that was previously used to run the server no longer exists (for example, an updated Java environment was installed and the old installation was removed). In that case, update the
config/java.propertiesfile to reference to path to the new Java installation and run thebin/dsjavapropertiescommand to apply that change. -
The Java installation used to run the server has been updated, and the server is trying to use the correct Java installation, but one or more of the options that had worked with the previous Java version no longer work with the new version. In that case, it is recommended that the server be re-configured to use the previous Java version, so that it can be run while investigating which options should be used with the new installation.
-
If an UNBOUNDID_JAVA_HOME or UNBOUNDID_JAVA_BIN environment variable is set, then its value might override the path to the Java installation used to run the server as defined in the
config/java.propertiesfile. Similarly, if an UNBOUNDID_JAVA_ARGS environment variable is set, then its value might override the arguments provided to the JVM. If this is the case, then explicitly unset the UNBOUNDID_JAVA_HOME, UNBOUNDID_JAVA_BIN, and UNBOUNDID_JAVA_ARGS environment variables before trying to start the server.
|
Any time the env UNBOUNDID_JAVA_HOME=/{pingauthorize}/java bin/dsjavaproperties
|
An invalid command-line option was provided
You might provide a small number of arguments when running the bin/start-server command, but in most cases, none are required. If you provided one or more command-line arguments for the bin/start-server command, and any one of them is not recognized, then the server provides an error message indicating that an argument was not recognized and displays version information. In that case, correct or remove the invalid argument and try to start the server again.
The server has an invalid configuration
If you make a change to the server configuration using an officially-supported tool like dsconfig or the administrative console, the server should validate that configuration change before applying it. However, it is possible that a configuration change can appear to be valid at the time that it is applied but does not work as expected when the server is restarted. Alternately, a change in the underlying system can cause a previously-valid configuration to become invalid.
In most cases involving an invalid configuration, the server displays (and writes to the error log) a message that explains the problem. This might be sufficient to identify the problem and understand what action needs to be taken to correct it. If the startup failure does not provide enough information to identify the problem with the configuration, then look in the logs/config-audit.log file to see what recent configuration changes have been made with the server online, or in the config/archived-configs directory to see if there might have been a recent configuration change resulting from a direct change made to the configuration file itself, rather than through a supported configuration interface.
If the server does not start as a result of a recent invalid configuration change, then it can be possible to start the server using the configuration that was in place the last time that the server started successfully (for example, the last known-good configuration). This can be achieved using the --useLastKnownGoodConfig option. For example:
$ bin/start-server --useLastKnownGoodConfigIf it has been a long time since the server was started and a number of configuration changes have been made since that time, then the last known-good configuration can be significantly out of date. In such cases, it can be preferable to manually repair the configuration.
If there is no last known-good configuration, if the server no longer starts with the last known-good configuration, or if the last known-good configuration is significantly out of date, then manually update the configuration by editing the config/config.ldif file.
|
Before editing the In addition to manually editing the configuration file, you can look at previous archived configurations to see if the most recent one works. You can also use the |
You do not have sufficient permissions
The server should only be started by the user or role used to initially install the server. In most cases, if an attempt is made to start the server as a user or role other than the one used to create the initial configuration, the server fails to start, because the user doesn’t have sufficient permissions to access files owned by the other user, such as database and log files.
However, if a non-root user installs the server and then the root account starts the server, it becomes impossible for a non-root user to start the server. This is because newly created files are owned by root and can’t be written to by other users.
If the server is unintentionally started by root, or if you wish to change the user account that should be used to run the server, change ownership on all files in the server installation so that they are owned by the user or role under which the server should run. For example, if the server should be run as the ds user in the other group, then run the following command as the root user:
chown -R ds:other /ds/the