Troubleshooting - Revision history

Craig: Remove pre-4.x version references (4.0.0 is the oldest documented release)

2026-07-31T15:02:30Z

Remove pre-4.x version references (4.0.0 is the oldest documented release)

← Older revision		Revision as of 15:02, 31 July 2026
Line 58:		Line 58:

	The quick start method runs Obsidian in a separate process to ensure you can gracefully stop it. Unfortunately, the separate process is failing before you can see what the problem is. To temporarily see the error and have it try to run in the same process, open the script in a text editor and find the line that launches Java: in <code>webObsidian.bat</code> it begins with <code>start "Obsidian" java</code>, and in <code>standaloneObsidian.bat</code> it begins with <code>start java</code>. Remove the <code>start</code> command and its window title if present (so the line begins with <code>java</code>), save the file and try again. You should get an informative message. Correct the underlying cause, restore the original line and run it again.		The quick start method runs Obsidian in a separate process to ensure you can gracefully stop it. Unfortunately, the separate process is failing before you can see what the problem is. To temporarily see the error and have it try to run in the same process, open the script in a text editor and find the line that launches Java: in <code>webObsidian.bat</code> it begins with <code>start "Obsidian" java</code>, and in <code>standaloneObsidian.bat</code> it begins with <code>start java</code>. Remove the <code>start</code> command and its window title if present (so the line begins with <code>java</code>), save the file and try again. You should get an informative message. Correct the underlying cause, restore the original line and run it again.






Line 139:		Line 135:
	If you have set a smaller value (e.g. 10), and have a very large amount of API or job activity, you can try increasing this value.		If you have set a smaller value (e.g. 10), and have a very large amount of API or job activity, you can try increasing this value.

	Most frequently though, this issue arises because Obsidian is configured to use a JNDI data source with its own connection pool, and there are incompatibilities between the pools' settings. As a rule, your JNDI database pool maximum size must be equal to or greater than the the maximum size of the Obsidian pool via property <code>com.carfey.obsidian.db.maxConnections</code> as outlined in [[Advanced_Configuration#Database_Properties\|Advanced Configuration]]. In addition, if there is an eviction process for idle connections, ensure than the value for the maximum idle age is 65 seconds or above to avoid warnings about unreleased connections. Alternatively~~, as of Obsidian 3.4.0~~, you can disable the Obsidian connection pool entirely by specifying <code>com.carfey.obsidian.db.disablePooling=true</code> in your <code>com.carfey.properties</code> file. This will cause Obsidian to never cache an opened idle connection.		Most frequently though, this issue arises because Obsidian is configured to use a JNDI data source with its own connection pool, and there are incompatibilities between the pools' settings. As a rule, your JNDI database pool maximum size must be equal to or greater than the the maximum size of the Obsidian pool via property <code>com.carfey.obsidian.db.maxConnections</code> as outlined in [[Advanced_Configuration#Database_Properties\|Advanced Configuration]]. In addition, if there is an eviction process for idle connections, ensure than the value for the maximum idle age is 65 seconds or above to avoid warnings about unreleased connections. Alternatively, you can disable the Obsidian connection pool entirely by specifying <code>com.carfey.obsidian.db.disablePooling=true</code> in your <code>com.carfey.properties</code> file. This will cause Obsidian to never cache an opened idle connection.

	Here is a good base JNDI pool configuration for Tomcat 7.		Here is a good base JNDI pool configuration for Tomcat 7.

Craig at 21:47, 30 July 2026

2026-07-30T21:47:15Z

← Older revision		Revision as of 21:47, 30 July 2026
Line 58:		Line 58:

	The quick start method runs Obsidian in a separate process to ensure you can gracefully stop it. Unfortunately, the separate process is failing before you can see what the problem is. To temporarily see the error and have it try to run in the same process, open the script in a text editor and find the line that launches Java: in <code>webObsidian.bat</code> it begins with <code>start "Obsidian" java</code>, and in <code>standaloneObsidian.bat</code> it begins with <code>start java</code>. Remove the <code>start</code> command and its window title if present (so the line begins with <code>java</code>), save the file and try again. You should get an informative message. Correct the underlying cause, restore the original line and run it again.		The quick start method runs Obsidian in a separate process to ensure you can gracefully stop it. Unfortunately, the separate process is failing before you can see what the problem is. To temporarily see the error and have it try to run in the same process, open the script in a text editor and find the line that launches Java: in <code>webObsidian.bat</code> it begins with <code>start "Obsidian" java</code>, and in <code>standaloneObsidian.bat</code> it begins with <code>start java</code>. Remove the <code>start</code> command and its window title if present (so the line begins with <code>java</code>), save the file and try again. You should get an informative message. Correct the underlying cause, restore the original line and run it again.






			= My Obsidian systemd service stops when I log out of Linux =

			The unit installed by <code>linux/install-embedded-linux-integration.sh</code> is a '''user''' service, so systemd stops it when the user's last session ends and does not start it at boot. Enable lingering for the account:

			loginctl enable-linger <nowiki><username></nowiki>

			Then confirm the service is enabled:

			systemctl --user is-enabled obsidian-embedded@scheduler.service

			If the service must run independently of any user account, create your own unit under <code>/etc/systemd/system/</code> based on <code>linux/obsidian-embedded@.service.in</code> in your install directory. See [[Getting_Started#Running_Obsidian_as_a_Linux_user_service\|Running Obsidian as a Linux user service]].

	= I tried running Obsidian in Jetty, but encountered the error "There is an error in invoking javac. A full JDK (not just JRE) is required" =		= I tried running Obsidian in Jetty, but encountered the error "There is an error in invoking javac. A full JDK (not just JRE) is required" =

	~~TThis~~ applies to Obsidian 4.x through 6.x deployed to your own Jetty installation. It is caused by Jetty wanting a JDK for JSP compilation when it isn't configured.		This applies to Obsidian 4.x through 6.x deployed to your own Jetty installation. It is caused by Jetty wanting a JDK for JSP compilation when it isn't configured.

	The simplest way to resolve this is to uncomment the following line from <code>start.ini</code> in your Jetty installation by removing the hash sign:		The simplest way to resolve this is to uncomment the following line from <code>start.ini</code> in your Jetty installation by removing the hash sign:

Craig at 21:39, 30 July 2026

2026-07-30T21:39:51Z

← Older revision		Revision as of 21:39, 30 July 2026
Line 61:		Line 61:
	= I tried running Obsidian in Jetty, but encountered the error "There is an error in invoking javac. A full JDK (not just JRE) is required" =		= I tried running Obsidian in Jetty, but encountered the error "There is an error in invoking javac. A full JDK (not just JRE) is required" =

	~~This~~ is caused by Jetty wanting a JDK for JSP compilation when it isn't configured.		TThis applies to Obsidian 4.x through 6.x deployed to your own Jetty installation. It is caused by Jetty wanting a JDK for JSP compilation when it isn't configured.

	The simplest way to resolve this is to uncomment the following line from <code>start.ini</code> in your Jetty installation by removing the hash sign:		The simplest way to resolve this is to uncomment the following line from <code>start.ini</code> in your Jetty installation by removing the hash sign:
Line 68:		Line 68:
	# -Dorg.apache.jasper.compiler.disablejsr199=true		# -Dorg.apache.jasper.compiler.disablejsr199=true
	</pre>		</pre>

			Obsidian 7.0.0 is tested on Tomcat 10.x and its WARs contain no JSPs, so no JSP compilation — and therefore no JDK — is required.

	= My jobs aren't running and I'm seeing this error: "Licence was refused: Licence is valid but no keys are available for lease. Are you running too many nodes?" =		= My jobs aren't running and I'm seeing this error: "Licence was refused: Licence is valid but no keys are available for lease. Are you running too many nodes?" =

Craig at 21:37, 30 July 2026

2026-07-30T21:37:16Z

← Older revision		Revision as of 21:37, 30 July 2026
Line 59:		Line 59:
	The quick start method runs Obsidian in a separate process to ensure you can gracefully stop it. Unfortunately, the separate process is failing before you can see what the problem is. To temporarily see the error and have it try to run in the same process, open the script in a text editor and find the line that launches Java: in <code>webObsidian.bat</code> it begins with <code>start "Obsidian" java</code>, and in <code>standaloneObsidian.bat</code> it begins with <code>start java</code>. Remove the <code>start</code> command and its window title if present (so the line begins with <code>java</code>), save the file and try again. You should get an informative message. Correct the underlying cause, restore the original line and run it again.		The quick start method runs Obsidian in a separate process to ensure you can gracefully stop it. Unfortunately, the separate process is failing before you can see what the problem is. To temporarily see the error and have it try to run in the same process, open the script in a text editor and find the line that launches Java: in <code>webObsidian.bat</code> it begins with <code>start "Obsidian" java</code>, and in <code>standaloneObsidian.bat</code> it begins with <code>start java</code>. Remove the <code>start</code> command and its window title if present (so the line begins with <code>java</code>), save the file and try again. You should get an informative message. Correct the underlying cause, restore the original line and run it again.

	~~= I'm trying to start Obsidian Web UI using the Quick Start method, but i'm getting an error about missing JAVA_HOME or tools.jar or Unable to find a javac compiler. What do I do? =~~		= I tried running Obsidian in Jetty, but encountered the error "There is an error in invoking javac. A full JDK (not just JRE) is required" =

	You need to let Winstone, the servlet container that is used for the Quick Start method, know about the JDK. It needs a JDK to be able to compile the JSPS. The installer tries to find one to configure Winstone properly, but isn't always able to do so.

	~~Usually, a global environment variable called <code>JAVA_HOME</code> will do the trick - see [https://docs.oracle.com/cd/E19182-01/820-7851/inst_cli_jdk_javahome_t/ Setting JAVA_HOME].~~

	Another option is to use a directive that points to your JDK only for winstone. You can either add the <code>--javaHome=...</code> directive in the <code>webObsidian.sh</code> or </code>webObsidian.bat</code> command following the last of other directives (--config=%file% or --config=$file). Or you can add the <code>--javaHome=...</code> directive the <code>winstone.properties</code> and/or <code>winstoneAdminOnly.properties</code> file(s).

	= I tried running Obsidian in Jetty 9, but encountered the error "There is an error in invoking javac. A full JDK (not just JRE) is required" =

	This is caused by Jetty wanting a JDK for JSP compilation when it isn't configured.		This is caused by Jetty wanting a JDK for JSP compilation when it isn't configured.

Craig: /* I'm trying to start Obsidian on Windows using the Quick Start method, but a window appears and then disappears quickly. What's going on? */

2026-07-30T21:34:01Z

I'm trying to start Obsidian on Windows using the Quick Start method, but a window appears and then disappears quickly. What's going on?

← Older revision		Revision as of 21:34, 30 July 2026
Line 57:		Line 57:
	= I'm trying to start Obsidian on Windows using the Quick Start method, but a window appears and then disappears quickly. What's going on? =		= I'm trying to start Obsidian on Windows using the Quick Start method, but a window appears and then disappears quickly. What's going on? =

	The quick start method runs Obsidian in a separate process to ensure you can gracefully stop it. Unfortunately, the separate process is failing before you can see what the problem is. To temporarily see the error and have it try to run in the same process, open ~~webObsidian.bat or standaloneObsidian.bat~~ in a text editor and find the line that begins with <code>start java</code>. Remove the ~~word '''~~start~~'''~~, save the file and try again. You should get an informative message. Correct the underlying cause, restore the ~~'''start''' command~~ and run it again.		The quick start method runs Obsidian in a separate process to ensure you can gracefully stop it. Unfortunately, the separate process is failing before you can see what the problem is. To temporarily see the error and have it try to run in the same process, open the script in a text editor and find the line that launches Java: in <code>webObsidian.bat</code> it begins with <code>start "Obsidian" java</code>, and in <code>standaloneObsidian.bat</code> it begins with <code>start java</code>. Remove the <code>start</code> command and its window title if present (so the line begins with <code>java</code>), save the file and try again. You should get an informative message. Correct the underlying cause, restore the original line and run it again.

	= I'm trying to start Obsidian Web UI using the Quick Start method, but i'm getting an error about missing JAVA_HOME or tools.jar or Unable to find a javac compiler. What do I do? =		= I'm trying to start Obsidian Web UI using the Quick Start method, but i'm getting an error about missing JAVA_HOME or tools.jar or Unable to find a javac compiler. What do I do? =

Craig: /* I'm trying to start Obsidian using the Quick Start method, but I'm seeing "java.net.BindException". */

2026-07-30T21:31:34Z

I'm trying to start Obsidian using the Quick Start method, but I'm seeing "java.net.BindException".

← Older revision		Revision as of 21:31, 30 July 2026
Line 50:		Line 50:
	# Use the "sudo" command to elevate your privileges to bind on a privileged port.		# Use the "sudo" command to elevate your privileges to bind on a privileged port.
	# Change the port you use.		# Change the port you use.
	To change the port ~~you use:~~
	* As of Obsidian 7.0.0		To change the port, edit the <code>-Dembedded.tomcat.http.port</code> value in <code>webObsidian.sh</code> or <code>webObsidian.bat</code>, or pass it as a JVM argument when starting Obsidian. The companion <code>-Dembedded.tomcat.stop.port</code> (default 9597) must also be free. If you run the Linux user systemd service, edit the script rather than the unit — the unit invokes the script. See [[Getting_Started#Starting_Obsidian_with_embedded_Tomcat\|Starting Obsidian with embedded Tomcat]].
	** Edit the <code>-Dembedded.tomcat.http.port</code> value in <code>webObsidian.sh</code> or <code>webObsidian.bat</code>, or pass it as a JVM argument. The companion <code>-Dembedded.tomcat.stop.port</code> (default 9597) must also be free. If you run the Linux user systemd service, edit the script — the unit invokes it. See [[Getting_Started#Starting_Obsidian_with_embedded_Tomcat\|Starting Obsidian with embedded Tomcat]].
	* Obsidian 2.~~4.0 through~~ 6.x		On Obsidian 5.x and 6.x, which bundled Jetty for the quick start instead of embedded Tomcat, change the port in the Jetty configuration or in the same <code>webObsidian</code> scripts.
	** Edit the port in the quick-start ~~container configuration (<code>winstone.properties</code> / <code>winstoneAdminOnly.properties</code> on older releases~~, or the Jetty configuration ~~on 5.x and 6.x),~~ or in <code>webObsidian~~.sh~~</code> ~~/ <code>webObsidian~~.~~bat</code>.~~
	* Before Obsidian 2.4.0
	** If using the Ant script, change the <code>deployPort</code> setting: <code>ant run.war -DdeployPort=8080 -Dspawn=true</code>

	= I'm trying to start Obsidian on Windows using the Quick Start method, but a window appears and then disappears quickly. What's going on? =		= I'm trying to start Obsidian on Windows using the Quick Start method, but a window appears and then disappears quickly. What's going on? =

Craig at 21:28, 30 July 2026

2026-07-30T21:28:13Z

← Older revision		Revision as of 21:28, 30 July 2026
Line 43:		Line 43:
	</pre>		</pre>

	This is a common error on *nix platforms, including OS X. On these platforms, ports 0-1023 are privileged. By default, only the root user will be able to bind to them. Obsidian's quick start ~~default configuration~~ uses port 8080~~, but perhaps~~ the port is already in use.		This is a common error on *nix platforms, including OS X. On these platforms, ports 0-1023 are privileged. By default, only the root user will be able to bind to them. Obsidian's quick start uses port 8080 by default; the error also occurs if that port is already in use.

	Changing the port as described below will fix the issue.		Changing the port as described below will fix the issue.
Line 51:		Line 51:
	# Change the port you use.		# Change the port you use.
	To change the port you use:		To change the port you use:
	* As of Obsidian 2.4.0		* As of Obsidian 7.0.0
	** Edit the ~~files~~ <code>winstone.properties</code>, <code>winstoneAdminOnly.properties</code>, <code>webObsidian.sh</code>, <code>webObsidian.bat</code> ~~to change the port used~~.		** Edit the <code>-Dembedded.tomcat.http.port</code> value in <code>webObsidian.sh</code> or <code>webObsidian.bat</code>, or pass it as a JVM argument. The companion <code>-Dembedded.tomcat.stop.port</code> (default 9597) must also be free. If you run the Linux user systemd service, edit the script — the unit invokes it. See [[Getting_Started#Starting_Obsidian_with_embedded_Tomcat\|Starting Obsidian with embedded Tomcat]].
	* Before Obsidian 2.4.0:		* Obsidian 2.4.0 through 6.x
			** Edit the port in the quick-start container configuration (<code>winstone.properties</code> / <code>winstoneAdminOnly.properties</code> on older releases, or the Jetty configuration on 5.x and 6.x), or in <code>webObsidian.sh</code> / <code>webObsidian.bat</code>.
			* Before Obsidian 2.4.0
	** If using the Ant script, change the <code>deployPort</code> setting: <code>ant run.war -DdeployPort=8080 -Dspawn=true</code>		** If using the Ant script, change the <code>deployPort</code> setting: <code>ant run.war -DdeployPort=8080 -Dspawn=true</code>
	** If using the command line to start Winstone, edit <code>winstone.properties</code> by setting the <code>httpPort</code> property to the desired value (e.g. 8080).

	= I'm trying to start Obsidian on Windows using the Quick Start method, but a window appears and then disappears quickly. What's going on? =		= I'm trying to start Obsidian on Windows using the Quick Start method, but a window appears and then disappears quickly. What's going on? =

Craig at 21:31, 17 May 2023

2023-05-17T21:31:05Z

← Older revision		Revision as of 21:31, 17 May 2023
Line 65:		Line 65:
	You need to let Winstone, the servlet container that is used for the Quick Start method, know about the JDK. It needs a JDK to be able to compile the JSPS. The installer tries to find one to configure Winstone properly, but isn't always able to do so.		You need to let Winstone, the servlet container that is used for the Quick Start method, know about the JDK. It needs a JDK to be able to compile the JSPS. The installer tries to find one to configure Winstone properly, but isn't always able to do so.

	Usually, a global environment variable called <code>JAVA_HOME</code> will do the trick - see [~~http~~://docs.oracle.com/cd/E19182-01/820-7851/inst_cli_jdk_javahome_t/ Setting JAVA_HOME].		Usually, a global environment variable called <code>JAVA_HOME</code> will do the trick - see [https://docs.oracle.com/cd/E19182-01/820-7851/inst_cli_jdk_javahome_t/ Setting JAVA_HOME].

	Another option is to use a directive that points to your JDK only for winstone. You can either add the <code>--javaHome=...</code> directive in the <code>webObsidian.sh</code> or </code>webObsidian.bat</code> command following the last of other directives (--config=%file% or --config=$file). Or you can add the <code>--javaHome=...</code> directive the <code>winstone.properties</code> and/or <code>winstoneAdminOnly.properties</code> file(s).		Another option is to use a directive that points to your JDK only for winstone. You can either add the <code>--javaHome=...</code> directive in the <code>webObsidian.sh</code> or </code>webObsidian.bat</code> command following the last of other directives (--config=%file% or --config=$file). Or you can add the <code>--javaHome=...</code> directive the <code>winstone.properties</code> and/or <code>winstoneAdminOnly.properties</code> file(s).
Line 110:		Line 110:
	</pre>		</pre>

	If you encounter an error like the one above and are using MySQL (particularly version 5.0), there is a chance you are hitting a [~~http~~://bugs.mysql.com/bug.php?id=20932 MySQL bug]. This problem seems to occur mainly on new Obsidian instances, so once corrected, there is a good chance you will never see the issue again.		If you encounter an error like the one above and are using MySQL (particularly version 5.0), there is a chance you are hitting a [https://bugs.mysql.com/bug.php?id=20932 MySQL bug]. This problem seems to occur mainly on new Obsidian instances, so once corrected, there is a good chance you will never see the issue again.

	Two approaches have been used with success:		Two approaches have been used with success:
	# In MySQL's my.cnf file, temporarily change (or add) the following line, and then restart mysqld: <pre>innodb_lock_wait_timeout = 600</pre><br />This appears to only be an issue when Obsidian first gets running, and it can typically be reverted after a while.<br /><br />		# In MySQL's my.cnf file, temporarily change (or add) the following line, and then restart mysqld: <pre>innodb_lock_wait_timeout = 600</pre><br />This appears to only be an issue when Obsidian first gets running, and it can typically be reverted after a while.<br /><br />
	# At a MySQL prompt, run the following command: <pre>optimize table semaphore;</pre><br /> If this resolves your issue, we suggest optimizing all your tables using [~~http~~://dev.mysql.com/doc/refman/5.0/en/mysqlcheck.html mysqlcheck].		# At a MySQL prompt, run the following command: <pre>optimize table semaphore;</pre><br /> If this resolves your issue, we suggest optimizing all your tables using [https://dev.mysql.com/doc/refman/8.0/en/mysqlcheck.html mysqlcheck].

	= I am running Obsidian on Oracle but I'm seeing the error "ORA-00942: table or view does not exist" =		= I am running Obsidian on Oracle but I'm seeing the error "ORA-00942: table or view does not exist" =

Craig: /* When I try to enter my job's class name in the UI, I get the message "Could not locate the class [MyJob]". What's the problem? */

2023-05-17T21:29:32Z

When I try to enter my job's class name in the UI, I get the message "Could not locate the class [MyJob]". What's the problem?

← Older revision		Revision as of 21:29, 17 May 2023
Line 16:		Line 16:

	# If you are running a combined scheduler and web application, the JAR file containing the job is not on the classpath of the servlet container (Tomcat/Jetty/etc). JARs are placed under <code>WEB-INF/lib</code> in the web application.		# If you are running a combined scheduler and web application, the JAR file containing the job is not on the classpath of the servlet container (Tomcat/Jetty/etc). JARs are placed under <code>WEB-INF/lib</code> in the web application.
	# If you are running a standalone web application with no scheduler running, your other Obsidian instance which includes the scheduler has not had its [[Implementing_Jobs#Classpath_Scanning\|Classpath Scanning]] configuration set, or has not been started with the appropriate classpath required for it to save the job metadata the web application uses to validate jobs. See [[Implementing_Jobs#~~Classpath_for_Building_and_Deploying~~\|Classpath for Building ~~and Deploying~~]].		# If you are running a standalone web application with no scheduler running, your other Obsidian instance which includes the scheduler has not had its [[Implementing_Jobs#Classpath_Scanning\|Classpath Scanning]] configuration set, or has not been started with the appropriate classpath required for it to save the job metadata the web application uses to validate jobs. See [[Implementing_Jobs#Classpath_for_Building\|Classpath for Building]].
	# Obsidian has not been restarted after updating the classpath with a new JAR.		# Obsidian has not been restarted after updating the classpath with a new JAR.
	# Job does not implement <code>com.carfey.ops.job.SchedulableJob</code>.		# Job does not implement <code>com.carfey.ops.job.SchedulableJob</code>.

Craig: /* Why isn't my job showing up? */

2023-05-17T21:28:20Z

Why isn't my job showing up?

← Older revision		Revision as of 21:28, 17 May 2023
Line 27:		Line 27:
	= Why isn't my job showing up? =		= Why isn't my job showing up? =

	Out of the box, Obsidian will display any previously scheduled jobs and Obsidian's bundled jobs. You can type in your class name as described in [[Admin_Jobs#~~Job_Nickname_and_Class~~\|Admin Jobs]].		Out of the box, Obsidian will display any previously scheduled jobs and Obsidian's bundled jobs. You can type in your class name as described in [[Admin_Jobs#Nickname.2C_Class_and_Folder\|Admin Jobs]].

	If you are using Obsidian's [[Implementing_Jobs#Classpath_Scanning\|classpath scanning]] and don't see your job pre-populated, make sure you set appropriate the "packageScannerPrefix" value in the [[Admin Scheduler Settings\|scheduler settings]] screen, and ensure the user account running Obsidian has read privileges to the <code>WEB-INF</code> directory of Obsidian's deployment directory.		If you are using Obsidian's [[Implementing_Jobs#Classpath_Scanning\|classpath scanning]] and don't see your job pre-populated, make sure you set appropriate the "packageScannerPrefix" value in the [[Admin Scheduler Settings\|scheduler settings]] screen, and ensure the user account running Obsidian has read privileges to the <code>WEB-INF</code> directory of Obsidian's deployment directory.