Platform > Operations

Troubleshooting Startup

This page covers the failures 3forge Enterprise reports at startup, what each one means, and where to look for further detail.

Overview

When startup fails, the script prints STARTUP FAILED and then searches the standard error log for the two most common causes: a license error and an explicit exit. The process exit code distinguishes the remaining cases.

Because the startup banner writes the JVM version, the applied JVM options, the classpath, and the main class to the standard output log before the process starts, that file is the first place to look for any failure.

Where to look

File	Look for
log/AmiCore.stdout	The startup banner, applied options, and Startup complete in
log/AmiCore.stderr	Stack traces, license errors, and exit reasons
log/AmiCore.log	Application logging after startup

Startup failures

License error

The startup script reports any line containing F1 LICENSE ERR from the standard error log.

Confirm that a license file exists in one of the locations the script searches, in order:

1. $HOME/f1license.txt
2. f1license.txt in the installation root
3. config/f1license.txt

Already running at this location

3forge AMI is already running at this location

The process could not acquire its lock, which means another instance is running from the same installation directory. The exit code is 2.

Stop the existing instance with scripts/stop.sh before starting another.

Already running on server port

3forge AMI is already running on server port

The process could not bind its listening port. The exit code is 2.

Either another 3forge Enterprise instance is using the port, or an unrelated process is. Check the configured ports in config/local.properties against what is in use on the host.

Configuration out of sync

YOUR defaults.txt IS INCONSISTENT WITH CURRENT VERSION

The shipped config/defaults.properties differs from the version the runtime was built with. A line-by-line difference is printed.

This most often means defaults.properties was edited directly, or an upgrade replaced the runtime library without replacing the defaults file. Move your changes into config/local.properties and restore the shipped defaults. See Configuration.

The startup script sets this check to warn rather than stop, so on a standard installation this message does not prevent startup.

Missing access file

If the access file authenticator is in use and data/access.txt is absent, the process stops. This is governed by exit.on.missing.users.access.file, which defaults to true.

Unrecognized failure

An exit code of 3 with Unknown Error in the standard error log means the failure was not one of the cases above. The stack trace in log/AmiCore.stderr is the only diagnostic.

Exit codes

Code	Meaning
1	Configuration rejected, including defaults out of sync when the check is set to stop
2	Another instance is already running, either at this location or on the configured port
3	An unrecognized error during startup

Startup appears to hang

The startup script polls for Startup complete in in the standard output log, printing a dot per second. After sixty seconds it prints a message noting that startup is taking longer than usual, and continues waiting.

The script also checks on each poll that the process is still alive, so a process that has exited is reported rather than waited on. A genuine hang with the process alive points at something the runtime is waiting for, such as a datasource connection or a component that has not reported ready.