This document is designed to help troubleshoot some commonly seen issues while installing or upgrading the ThingWorx application, prior or instead of contacting Tech Support. This is not a defined template for a guaranteed solution, but rather a reference guide that provides an opportunity to eliminate some of the possible root causes.
While following the installation guide and matching the system requirements is sufficient to get a successfully running instance of ThingWorx, some issues could still occur upon launching the app for the first time. Generally, those issues arise from minor environmental details and can be easily fixed by aligning with the proper installation process.
Currently, the majority of the installation hiccups are coming from the postgresql side. That being said, the very first thing to note, whether it's a new user trying out the platform or a returning one switching the database to postgresql, note that: Postgresql database must be installed, configured, and running prior to the further Thingworx installation.
Generally, this type of error point at the security/permission issue. As all of the installation operations should be performed by a root/Administrator role, the following points should be verified:
- Blank screen, no errors in the logs, "waiting for <url> " gears running be never actually loading, eventually times out
- Ensure that Java in tomcat is pointing to the right path, should be something like this:
- C:\Program Files\Java\jre1.8.0_101\bin\server\jvm.dll
- Error when executing thingworxpostgresDBSetup.bat psql:./thingworx-database-setup.sql:1: ERROR: could not set permissions on directory "D:/ThingworxPostgresqlStorage": Permission denied
The error means that the postgres user was not able to create a directory in the ‘ThingworxPostgresStorage’ directory. As it's related to the security/permission, the following steps can be taken to clear out the error:
- Assigning read/write permissions to everyone user group to fix the script execution and then execute the batch file:
- Right-click on ‘ThingworxPostgresStorage’ directory -> Share with -> specific people.
- Select drop-down, add everyone group and update the permission level to Read/Write.
- Click Share.
- Executing the batch file as admin.
2. Installation error message "relation root_entity_collection does not exist" is displayed with Postgresql version of the ThingWorx platform.
Such an error message is displayed only if the schema parameter passed to thingworxPostgresSchemaSetup.sh script is different than $USER or PUBLIC. To clear out the error:
- Edit the Postgresql configuration file, postgresql.conf, to add to the SEARCH_PATH item your own schema.
Other common errors upon launching the application.
Two of the most commonly seen errors are 404 and 401. While there can be a numerous reasons to see those errors, here are the root causes that fall under the "very likely" category:
- 404 Application not found during a new install:
- Ensure Thingworx.war was deployed -- check the hard drive directory of Tomcat/webapps and ensure Thingworx.war and Thingworx folder are present as well as the ThingworxStorage in the root (or custom selected location)
- Ensure the Thingworx.war is not corrupted (may re-download from the support and compare the size)
- 401 Application cannot be accessed during a new install or upgrade:
- For Postgresql, ensure the database is running and is connected to, also see the Basic Troubleshooting points below.
- Verify the tomcat, java, and database (in case of postgresql) versions are matching the system requirement guide for the appropriate platform version
- Ensure the updrade was performed according to the guide and the necessary folders were removed (after copying as a preventative measure).
- Ensure the correct port is specified in platform-settings.json (for Postgresql), by default the connection string is jdbc:postgresql://localhost:5432/thingworx
Again, it should be kept in mind that while the symptoms are common and can generally be resolved with the same solution, every system environment is unique and may require an individual approach in a guaranteed resolution.
Basic troubleshooting points for:
- Validating PostgreSQL installation
- Postgres install troubleshooting
- java.lang.NullPointerException error during PostgreSQL installation
- ***CRITICAL ERROR: permission denied for relation root_entity_collection
- Error while running scripts: Could not set permissions on directory "/ThingworxPostgresqlStorage":Permission Denied
- Acquisition Attempt Failed error
- Ensure 'ThingworxStorage', 'ThingworxPlatform' and 'ThingworxPostgresqlStorage' folders are created
- The folders have to be present in the root directory unless specifically changed in any configurations
- Recommended to grant sufficient privileges (if not all) to the database user (twadmin)
- Note: While running the script in order to create a database, if a schema name other than 'public' is used, the "search_path" in "postgresql.conf" must be changed to reflect 'NewSchemaName, public'
- Grant permission to user for access to root folders containing 'ThingworxPostgresqlStorage' and 'ThingworxPlatform'
- The password set for the default 'twadmin' in the pgAdmin III tool must match the password set in the configuration file under the ThingworxPlatform folder
- Ensure THINGWORX_PLATFORM_SETTINGS variable is set up
psql:./thingworx-database-setup.sql:14: ERROR: could not create directory "pg_tblspc/16419/PG_9.4_201409291/16420": No such file or directory
psql:./thingworx-database-setup.sql:16: ERROR: database "thingworx" does not exist
Replacing /ThingworxPostgresqlStorage in the .bat file by C:\ThingworxPostgresqlStorage and omitting the -l option in the command window.
Also, note the following error Troubleshooting Syntax Error when running postgresql set up scripts