Troubleshooting guide

This is a list of common issues you may face during the development of your connector and how to solve them. They are categorized by the stage of development in which they may arise.

If you come across a problem that is not covered below, please raise an issue here.

Where to check for errors

Log files

The i2 Analyze server logs can be found in the i2analyze\deploy\wlp\usr\servers\opal-server\logs\ directory.

  • console.log is the main server log file.
  • opal-services-daod\i2_Analysis_Repository.log is where errors with your connector configuration and/or data will appear.

Connector configuration errors

"Failed to retrieve configuration information for the connector with identifier '<CONNECTOR_ID>' from the URL '<URL>'"

You will see this in the output when running setup -t start if i2 Analyze fails to retrieve your connector's configuration from its config endpoint. Check that the base URL printed here is correct. If not, update the connector base url given in the i2 Analyze topology.xml file (in the i2analyze\toolkit\configuration\environment directory). If the URL is correct, then you need to check the implementation of your config endpoint and that you have assigned to it the correct URL path. This should be the base URL suffixed with "/config".

"The service [...] specifies an unknown semantic property type identifier [...]. The identifier must be present in the core semantic type library, or in the semantic types that connector or gateway schemas define, or in the Information Store schema (if present)."

You will see this in the output when running setup -t start if your connector includes a service that specifies semantic seed constraints, and the server detects a problem with the semantic type identifiers that the service uses.

During connector development, the message usually means that you made a mistake when you added the identifier to the service configuration - a copy-and-paste error, or something similar. The detail in the message will suggest the solution.

If you see the message during deployment of a connector to a production system, it is more likely that the version of the i2 Semantic Type Library on the i2 Analyze server is older than the version that was used during development. In this situation, you must update the server with the latest version of the i2 Semantic Type Library.

"Some queries are not configured correctly. Contact your system administrator."

Some queries are not configured correctly

You will see this in the External Searches window if there is a problem with your connector configuration. Clicking DETAILS will provide more information. Problems might include:

  • No acquireUrl defined for a service: make sure you define one in the service definition

  • The application is communicating with the connector through a protocol that is insecure. You will see this because i2 Analyze and your connector communicate via HTTP.

    In a production environment, you should secure this connection by using HTTPS. This is beyond the scope of this guide, but is covered in the i2 product documentation.

Errors running connector services

"Failed to open the selected query. Contact your system administrator"

Failed to open the selected query

If you see the above error message when trying to run a query defined by your connector via External Searches in Analysts's Notebook, there are a number of potential causes. To understand what went wrong:

  1. Look at the log file: i2analyze\deploy\wlp\usr\servers\opal-server\logs\opal-services-daod\i2_Analysis_Repository.log

  2. You should see at the bottom a more detailed description of the error that occurred. You will most likely see an error message starting with the following:

    d484-4e04-97d5-86e771fed434  - Validation error while retrieving a record.
- The service with identifier '<SERVICE_NAME>' on the connector with identifier '<CONNECTOR_ID>' returned invalid data

    Below this line will be more specific information about why the query failed. Examples and their solutions are given below.

"The schema does not contain an entity/a link/a property with identifier '<TYPE_ID>'"

This means you have supplied an entity or link with a typeId that does not exist in your schema. Check that the typeId you supplied is not a typo.

"The value '<PROPERTY_VALUE>' is not valid for the property type with identifier '<TYPE_ID>'. The value '<PROPERTY_VALUE>' is incompatible with the '<LOGICAL_TYPE>' data type."

This means that the property value you supplied is not in the correct format, which is defined by the logical type of the property. This is especially common when dealing with DATE, TIME and DATETIME properties.

Check that you have assigned an appropriate logical type for this property and see the data model examples to understand the required format for each logical type.