Skip to main content

Troubleshoot the Kepware Integration

availability
Feature availability by platform, plan type, and user type
Platform:AvailableWebNot availableMobile
Plan Type:Not availableBasicNot availableEssentialAvailablePremiumAvailableEnterprise
User Type:Not availableRequesterNot availableFull UserAvailableAdministrator

If the Kepware integration or its Kepware agent isn't behaving as expected, use the sections below to identify and resolve common issues.

Not Seeing Data in MaintainX®​

If tags aren't being created or their values aren't updating in MaintainX, work through the following checks:

  • Confirm the Kepware agent in KEPServerEX still uses the default message format. Modifying the message template causes the agent to send data MaintainX can't process. For more information, see Configure the Kepware Agent.
  • Confirm Max events per is set to 1,000 or lower. The MaintainX platform rejects any request that exceeds this limit.
  • Confirm the URL on the Rest Client - Endpoint page points to the agent endpoint for your organization's region. For more information, see Choose Your Region.
  • Confirm the access token in the Authorization header is correct and hasn't been revoked.
  • In KEPServerEX, right-click the Kepware agent and select Events to check for connection or delivery errors. For more information, see Kepware Event Log Errors.

Only Some Tags Appear in MaintainX​

If some tags appear in MaintainX and others never do, check the following causes:

  • Invalid tag path: MaintainX identifies each tag by its full Channel.Device.Tag path. A tag whose path has fewer than three parts, separated by periods, is rejected. Tags in a group, such as Channel.Device.Group.Tag, are valid.
  • Unsupported value type: MaintainX accepts only number, string, and boolean values. It rejects tags that publish arrays, structures, or null values. Add the individual scalar tags to the Kepware agent instead. For more information, see Supported Data Types.
  • Kepware license limit: The IoT Gateway license allows a fixed number of tags. Each agent counts its tags separately, and tags that aren't enabled still count. When the limit is reached, Kepware loads only the licensed number of tags and logs an event that states the licensed item count has been reached. Remove tags you don't need from the agent, or upgrade your Kepware license.

MaintainX processes the valid tags in a request even when other tags in the same request are rejected.

Data Arrives Late After an Outage​

When the Buffer on Failed Publish setting is Yes and the Kepware agent can't deliver data to MaintainX, the agent holds the data in memory until delivery succeeds. Common causes of failed delivery include a revoked token, a wrong URL, or a network outage. After you correct the problem, the agent sends the buffered data to MaintainX.

The agent buffers up to 100,000 events. When the buffer is full, Kepware drops new data. To prevent data loss, resolve connection problems promptly.

Tag Values Look Stale​

When a tag's quality in Kepware changes to Bad, such as when a device stops responding, Kepware sends one update with that quality and then no further updates until the quality returns to Good.

To find the cause, check the device connection in KEPServerEX.

Renamed Tags Appear as New Tags​

MaintainX identifies each tag by its full Channel.Device.Tag path. If you rename a channel, device, or tag in Kepware, the renamed tag appears in MaintainX as a new tag. Data stops updating the original tag, and you must map the new tag to a meter. To avoid this, don't rename channels, devices, or tags that are already sending data to MaintainX.

Kepware Event Log Errors​

To check for errors, right-click the Kepware agent in KEPServerEX and select Events. The following table lists common messages and their resolutions:

MessageCauseResolution
Connection refused: connectThe endpoint is unreachable.Confirm the URL is correct and that no firewall blocks outbound HTTPS traffic from the Kepware host.
Read timed outThe URL uses the wrong protocol, or the server is slow to respond.Confirm the URL begins with https://. If the problem continues, review the Timeout (s) setting.
SSL configuration errorThe Kepware host doesn't trust the server's certificate.Confirm the Windows host trusts the certificate chain for the endpoint. If your network inspects TLS traffic through a proxy, the host must also trust the proxy's root certificate.
returned HTTP error 401The access token is missing, wrong, revoked, or from a different region.Confirm the access token in the Authorization header and the region of the URL. For details, see Choose Your Region.
returned HTTP error 404The URL path is wrong.Confirm the URL matches the endpoint for your region. For details, see Choose Your Region.
published events buffer is fullThe agent can't deliver data as fast as it collects it.Reduce the number of tags on the agent or increase the Scan Rate of its IoT Items. Don't increase Max events per above 1,000, because MaintainX rejects larger requests.
licensed item count … has been reachedThe agent has more tags than your Kepware license allows.Remove tags you don't need, or upgrade your Kepware license.
Failed to start IoT Gateway service or Unsupported JVMThe IoT Gateway can't start, usually because of a Java problem.Confirm that a supported version of Java is installed on the Kepware host.

Contact MaintainX Support​

If your issue isn't listed here or you continue to experience problems, contact MaintainX Support. Include the Kepware agent events from KEPServerEX to help us investigate.