Troubleshooting

This section provides information on the following issues:

Atelier is Slow or Unresponsive at Start Up

If Atelier is slow or unresponsive when starting, it may be because of the processing required to index large databases. See Improving Start-up Performance for information how to solve this problem.

Terminating Long-running Processes

Some actions in Atelier can take a long time to complete and consume a large percentage of resources while they are running, which has a negative impact on performance. Actions that make heavy use of the parser or the network can fall into this category, as can tasks such as importing many classes and routines from an XML file, opening large files in an editor, and copying a large number of files from the server. If you would like to terminate such a long-running process, you can do so from the Progress View. You can open this view by selecting Window > Show View > Other > General > Progress from the main menu. You can also use double-click on the progress bar in the lower right of the workbench as a short cut.

Open progress view

In the progress view, click on the red button on the right to terminate the process.

Terminate process

Dialogs and views that show a progress bar often also have a red button that you can click to terminate the process.

Terminate process bar

See Responsive UI for additional information.

Installing new software

Connections and Secure Storage on Mac Platforms

Atelier uses the Eclipse secure storage mechanism to store connection information. Normally, access is handled by Atelier without the need for user intervention. On Mac platforms, problems can arise with this system.

In some cases, secure storage becomes corrupted, and connections become unusable. Symptoms of corruption are:

The Workbench User Guide provides information on resolving problems with secure storage. You can also find more detailed information on the secure storage preference page

If none of the suggestions in these resources provide a lasting solution to the problem, as a last resort, disable use of your OS X keyring with Atelier by taking the following steps:

  1. Open the Window > Preferences wizard and select: command link General > Security > Secure Storage
  2. Select the Password tab.
  3. Disable the OS X Keystore Integration by clearing the check box.
  4. Select the Contents tab.
  5. Click the Delete button.
  6. A dialog appears warning you that this action will delete all secure storage. Select Yes.
  7. Answer Yes when you are asked if you want to restart Atelier.
  8. When you create a connection, you are asked to create a secure storage password. Enter a password, and supply password hints when prompted. If you are not prompted to create a password, go to the password tab on the secure storage preferences page and use the Change Password button to create a password for the UI Prompt password provider.
  9. You are now required to supply this password when you login to Atelier.

Forbidden or Service Unavailable Errors

If you receive an error that reads Forbidden: Check your security and license settings. or Service Unavailable: Check your security and license settings. consider the following possibilities when resolving the issue:

Network Activity and Error Logs

Atelier provides two views that can be helpful in troubleshooting. One is the standard Eclipse error log, which you can find at Window > Show View > Error Log. The other is a log of network activity. This view is specific to Atelier and can be found at Window > Show View > Other > Atelier > Network Activities. The information it provides can be useful in troubleshooting problems with communication between the Atelier client and the server.

Problems with Connection Authentication

Eclipse provides a default mechanism for authenticating HTTP connections. This default authenticator, called NetAuthenticator, enables the use of authenticated connections by providing a UI dialog to handle entry of credentials and other details. The Atelier plug-in overrides this default authenticator, as do many other Eclipse plug-ins. Installing the Atelier plug-in overrides the default authenticator, and any other authenticator provided by a plug-in you have installed. As a result, after you have installed Atelier, authentication in other plug-ins does not function as it did previously. Similarly, installing a plug-in that provides its own authentication mechanism overrides what Atelier has installed, and can alter authentication of connections in Atelier.

Plug-ins that supply an authenticator include:

If you are having problems with authenticated connections in Atelier or another Eclipse plug-in, contact the InterSystems Worldwide Response Center for information on how to resolve this issue.

Prohibited Authentication

If you see the following error when you test a server connection, it indicates that you are using the authentication mode Unauthenticated for the /api/atelier Web application. This authentication mode is not supported. You need to change it to Password authentication.

Prohibited authentication warning

If you see this error while creating a new connection, click Finish to create the connection. Then right-click on the connection in the Server Explorer and select Management Portal from the context menu. In the Management Portal, select System Administration > Security > Applications > Web Applications. Select /api/atelier from the list of defined Web applications. Edit the definition by clearing Unauthenticated and selecting Password, as shown in the following screen shot, and save your changes:

authentication method for atelier

Connection Failure with Locked Down Server

If a server is running in Locked Down security mode, the /api/atelier Web application is not enabled by default. When you create connections from Atelier to a locked down server, you get the error: Not Found. Check the web server configurations. To make the connection functional, you must enable the application, using the Management Portal. Right-click on the connection in the Server Explorer and select Management Portal from the context menu. In the Management Portal, select System Administration > Security > Applications > Web Applications. Select /api/atelier from the list of defined Web applications. Edit the definition by selecting Enable Application, as shown in the following screen shot, and save your changes:

Prohibited authentication warning

Unexpected Syntax Errors

If syntax errors appear in Atelier in previously error-free code, it may be because Atelier has detected syntax errors that Studio and the ObjectScript compiler did not detect. For example, due to a bug in Studio, code such as this was allowed:

syntax error allowed by Studio

When you encounter such anomalies, check the code for accuracy and edit where needed.

Synchronization Write Permission Errors

If synchronizing a project results in errors of the form:

ERROR #5883: Item 'filename' is mapped from a database that you do not have write permission on.

A likely reason is that you have copied files from one namespace to another, and the copied files are already mapped to the project's namespace from a database for which you do not have write permission.

For example, this problem can arise if you copy files from %SYS to a project mapped to USER. The %SYS files are all mapped to USER, so attempting to synchronize those files to the server always points to a read-only database which results in the error.

Update Fails on Mac

Due to recent security enhancements, if you are running on a Mac using macOS 10.12 or later, your Eclipse instance must be installed in the /Applications directory for Eclipse updates to work correctly. If it is installed in another directory, update fails with the error:

Cannot complete the request. See the error log for details.
Atelier IDE will be ignored because it is already installed, and updates are not permitted.

Put Workspace on a Local Drive

If you are not familiar with Eclipse, you might choose to store your workspace directory on a network drive. Doing so results in substantial delays during synchronization, as well as during the use of underlying Eclipse features related to the workspace. You should put the workspace on a local drive when possible. You can link resources from other locations if necessary. Since you will typically use source control, linked projects will be configured automatically (projects will be in their local repository workspace) with no additional effort.

Need IIS handler mapping for /api/atelier

When you configure Atelier to use an InterSystems database server on an IIS port, IIS needs a handler mapping for /api/atelier* to know how to handle the request.

InterSystems documentation on configuring IIS with the CSP Gateway recommends mapping *.csp, *.cls, *.zen and *.cxw to the CSP Gateway module. When you run the installer on a Windows machine and allow it to set up IIS with the CSP configuration, it creates *.csp, *.cls, *.zen and *.cxw handler mappings. With this default IIS configuration for the CSP Gateway, testing the connection to a server configured in Atelier throws the error "Not Found. Check the web server configurations."

For Atelier communication to the server, IIS needs a handler mapping at the IIS Default Web Site level so that REST requests are passed on to the CSP Gateway. Something like:

configuring /api/atelier* for IIS

Incompatible Templates

Template context options have changed between Atelier 1.0 and 1.1, which renders templates from 1.0 incompatible with a 1.1 instance. Templates from 1.0 imported into Atelier 1.1 are not visible. Any templates you created in 1.0 need to be recreated when you update to 1.1.

Eclipse Update Issues

There are known problems with updating the Eclipse IDE through the normal update mechanism. These problems are due to unresolved issues with Eclipse. InterSystems suggests downloading and installing the new Eclipse version, and installing Atelier and whatever other plugins you require.

Should you need to perform an Eclipse upgrade, here are some suggestions. What you may experience is that if you perform the update and restart Eclipse when prompted, when Eclipse launches you see a dialog box something like this:

Open progress view

If you click the Install button, the Eclipse installation reverts to the version level you were trying to update. Instead, follow these steps:

Legacy CDL Support

Atelier does not support syntax from Class Definition Language (CDL) versions less than version 25, which is the version compatible with Caché/Ensemble servers 2016.2 and later.

Saving a legacy file (one using a CDL version less than 25) to a current server automatically updates the contents of the file on both the server and the client, to match the CDL version supported by the server. Those version are:

The resulting syntax changes are viewed as file changes by your version control system. If it is important that the CDL version of the file not change, then save it only to servers with matching CDL support, or else use Studio.

Also note that valid syntax in files using a CDL version less than 25 may be marked as an error by the Atelier parser. Legacy files stored in XML format may fail UDL transformation and not be properly displayed in Atelier editors.

Related Eclipse documentation

Responsive UI
Installing new software
Secure storage

Related concepts

Updating and Extending Atelier

Related tasks

Improving Start-up Performance

Related reference

Connection Configuration
Connection Repair