Troubleshooting for error messages from the client and server.

General Error Troubleshooting

Environment did not respond to a CORS request properly

When encountering CORS issues with an environment, first check that the API server is running. Test this by opening a browser and appending /status to the API server URL within your browser.

The URL should return metadata about the environment. If data is not returned, it is likely the deployment failed. Review the server logs to determine what went wrong.

Unknown Component - Premium Components

The "Unknown Component" error pertains to a lack of access to the Premium Components library. Premium Components are distributed via PKG, which is included in our Enterprise subscriptions.

To resolve the error, confirm the Premium Components library is being included in your environment. If it is not, or you are unsure, please refer to the following documentation below.

Click here for Premium Library PKG instructions

If you have an Enterprise subscription and are unable to view the link above, or have not logged into our PKG before, please contact the customer support team at

If assistance is needed, please provide the support team with your username and email

License Error Troubleshooting

License utilization is disabled

"License utilization is disabled" means that you have exceeded the allotted servers within your license scope. The License Administrator can manage this by navigating to the License Management page.

There are two ways the License Admin can access their licenses. The first is by clicking the username at the top right of the page and then clicking the License Management button.

The second option is to navigate to the main Portal page and click the License Management button on the left-hand sidebar.

In the License Management section, the admin can view all of the API Servers associated with the license and disable the ones that are not in use while enabling the servers you wish to be active. Click here for more information on managing your License Key(s)

Could not read license. (Listening on port 80)

This error message usually indicates the wrong API Server version tag was pulled into the environment. It is not recommended to pull in the 'Latest' tag as this tag is often an RC version of a server is currently working on. Verify you are using the most updated, non-rc version of our server.

Server is in restricted method mode

If the server is in restricted mode, the license is not being validated by the server. After 12 hours of trying to validate the license key, the server will enter restricted mode.

This can happen when a firewall has blocked access to the endpoint. To resolve, enable your environment access to the license server so the license key can validate.

This error can also occur when the API Server is disabled within the License Management UI. The License Administrator can manage this by clicking the 'License Management' button underneath their profile username or from the main Portal page (see license utilization error details above). Enable the server from the License Management UI to resolve the error.

400 - a list of all 400 errors

DB is already locked for updating

A lock is put on the DB when a DB Update Hook is utilized or any other database update that is triggered by your codebase. ​A lock on the database for updates is expected, and the lock is removed upon successful updates.

If an update fails for any reason, the lock has the possibility of remaining and needs to be removed. Servers will attempt to restart until stopped.

Closely monitoring any upgrades to ensure the update is successful is recommended. Checking that the servers start as expected.

To remove, find the schema collection included in the database, which has only a few records in it. One of them will be a lock entry. You can remove that entry, and then restart the containers in order to resolve this issue.

Make sure not to remove the dbIdentifier entry as this is used for licensing.

Click here for more information on DB update failures

401 - a list of all 401 errors

Project is protected

A project in Protected mode can not be updated or deleted. Uncheck the 'Protected' flag within your Stage Settings to disable it.

Invalid Alias - Login Page

This error message usually indicates the Login URL contains a reserved name that is not permitted. Rename your Subdomain within your Stage Settings to resolve the issue.

Click here for a full list of reserved names

Mongo / Cosmos Errors

MongoServerError: The 'expiredAfterSeconds' is supported on '_ts' field only

This error is seen when CosmosDB is not configured correctly to work seamlessly in MongoDB mode as CosmosDB requires indexes to be set. This is not required when using MondoDB/AtlasDB.

Confirm you are using CosmosDB

Click here for CosmosDB Index documentation

In CosmosDB (set to MongoDB) version 3.6: In order to do a sort on a property, there must be an index set. This is different from how MongoDB works as MongoDB allows sorting on any property regardless of an index being set. To resolve this, a wildcard index can be added to the following collections:

db.submissions.createIndex( {"$**": 1 } ); db.forms.createIndex( {"$**": 1 } ); db.projects.createIndex( {"$**": 1 } ); db.actions.createIndex( {"$**": 1 } );' db.roles.createIndex( {"$**": 1 } );

DocumentDB Errors

MongoServerError: namespace name generated from index name is too long

DocumentDB limits the length of indexes, collection names, and index namespaces. If you're receiving this error, try shortening one of (a) the submission collection name, (b) the component name you're trying to index, or (c) the database name that the environment has been installed in.

Last updated