eMessage (GAS) Symptoms, Causes, and Actions
Each section below uses the symptom as its title and then provides the cause and actions to take to resolve the situation. Click a section title to display its content and when done, click again to hide the content.
Symptom: Call to startSession failed
When launching the client, a call to the startSession service on the device Thing is made. A number of initialization problems can cause this symptom:
1. CAUSE: The selected GAS instance is not accessible. The startSession workflow for GAS selects an available GAS instance and assigns it to handle the session.
ADMINISTRATOR ACTION: Check the logs for one of the eMessage Connectors through which the GAS can register, a log similar to the one below would have occurred. Note that which instance depends on the topology of the connector setup and is likely unpredicatble in load-balanced environments. Here is the log:
2018-12-31 06:15:21.057 [pool-4-thread-1] ERROR c.t.r.s.StartRemoteSessionHandler - Error starting remoteSession=RemoteSession{"agentDevice":"ra-test-agent","createdBy":"Administrator","remoteServer":"gas.ptciot.io","sessionId":"06c912d9-c870-4305-8eb8-b1b156906188","parameters":{"rows":[{"remoteEndpoint":"TERMINAL","providerConfig":{}}],"dataShape":{"fieldDefinitions":{"remoteEndpoint":{"name":"remoteEndpoint","aspects":{},"description":"remoteEndpoint","baseType":"STRING","ordinal":0},"providerConfig":{"name":"providerConfig","aspects":{},"description":"providerConfig","baseType":"JSON","ordinal":0}}}},"status":"INITIALIZING"}
com.thingworx.remoteaccess.services.client.RemoteAccessServerClientException: Global Access Server request error: url=https://gas.ptciot.io:8443/remote/mockservices/start-session
at com.thingworx.protocol.gas.services.client.GASClientImpl.handleGasResponse(GASClientImpl.java:325)
at com.thingworx.protocol.gas.services.client.GASClientImpl.lambda$startSession$0(GASClientImpl.java:130)
at java.util.concurrent.CompletableFuture.uniHandle(CompletableFuture.java:822)
at java.util.concurrent.CompletableFuture$UniHandle.tryFire(CompletableFuture.java:797)
at java.util.concurrent.CompletableFuture.postComplete(CompletableFuture.java:474)
at java.util.concurrent.CompletableFuture.completeExceptionally(CompletableFuture.java:1977)
at com.thingworx.protocol.transport.http.client.HttpClientImplVertx.lambda$complete$3(HttpClientImplVertx.java:78)
at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:511)
at java.util.concurrent.FutureTask.run(FutureTask.java:266)
at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142)
at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617)
at java.lang.Thread.run(Thread.java:745)
Caused by: com.thingworx.protocol.transport.http.client.HttpClientException: java.net.UnknownHostException: failed to resolve 'gas.ptciot.io' after 3 queries
... 6 common frames omitted
Caused by: java.net.UnknownHostException: failed to resolve 'gas.ptciot.io' after 3 queries
at io.netty.resolver.dns.DnsNameResolverContext.finishResolve(DnsNameResolverContext.java:721)
at io.netty.resolver.dns.DnsNameResolverContext.tryToFinishResolve(DnsNameResolverContext.java:663)
at io.netty.resolver.dns.DnsNameResolverContext.query(DnsNameResolverContext.java:306)
at io.netty.resolver.dns.DnsNameResolverContext.query(DnsNameResolverContext.java:295)
at io.netty.resolver.dns.DnsNameResolverContext.tryToFinishResolve(DnsNameResolverContext.java:636)
at io.netty.resolver.dns.DnsNameResolverContext$3.operationComplete(DnsNameResolverContext.java:342)
at io.netty.util.concurrent.DefaultPromise.notifyListener0(DefaultPromise.java:507)
at io.netty.util.concurrent.DefaultPromise.notifyListenersNow(DefaultPromise.java:481)
at io.netty.util.concurrent.DefaultPromise.notifyListeners(DefaultPromise.java:420)
at io.netty.util.concurrent.DefaultPromise.trySuccess(DefaultPromise.java:104)
at io.netty.resolver.dns.DnsQueryContext.setSuccess(DnsQueryContext.java:197)
at io.netty.resolver.dns.DnsQueryContext.finish(DnsQueryContext.java:180)
at io.netty.resolver.dns.DnsNameResolver$DnsResponseHandler.channelRead(DnsNameResolver.java:965)
at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:362)
at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:348)
at io.netty.channel.AbstractChannelHandlerContext.fireChannelRead(AbstractChannelHandlerContext.java:340)
at io.netty.handler.codec.MessageToMessageDecoder.channelRead(MessageToMessageDecoder.java:102)
at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:362)
at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:348)
at io.netty.channel.AbstractChannelHandlerContext.fireChannelRead(AbstractChannelHandlerContext.java:340)
at io.netty.channel.DefaultChannelPipeline$HeadContext.channelRead(DefaultChannelPipeline.java:1359)
at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:362)
at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:348)
at io.netty.channel.DefaultChannelPipeline.fireChannelRead(DefaultChannelPipeline.java:935)
at io.netty.channel.nio.AbstractNioMessageChannel$NioMessageUnsafe.read(AbstractNioMessageChannel.java:93)
at io.netty.channel.nio.NioEventLoop.processSelectedKey(NioEventLoop.java:645)
at io.netty.channel.nio.NioEventLoop.processSelectedKeysOptimized(NioEventLoop.java:580)
at io.netty.channel.nio.NioEventLoop.processSelectedKeys(NioEventLoop.java:497)
at io.netty.channel.nio.NioEventLoop.run(NioEventLoop.java:459)
at io.netty.util.concurrent.SingleThreadEventExecutor$5.run(SingleThreadEventExecutor.java:886)
at io.netty.util.concurrent.FastThreadLocalRunnable.run(FastThreadLocalRunnable.java:30)
... 1 common frames omitted
I
If these messages appear in the log, it is likely that the GAS instance is unavailable for some reason. To resolve the issue, either ensure that the GAS instance is up and able to communicate to the desired eMessage Connector instances, or disable the GAS Thing by setting its enabledForRemoteSessions property to false.
2. CAUSE: No enabled GAS instances exist.
ADMINISTRATOR ACTION: Ensure that a GAS instance is registered with theh platform. Run the EnableForRemoteSessions service on the Thing that is provisioned when the GAS instance registers with ThingWorx.
3. CAUSE: The GAS instance is configured with an invalid host name.
ADMINISTRATOR ACTION: Ensure that the GAS instance is configured to register with a host name that resolves correctly. It may be necessary to delete the GAS Thing and restart the GAS instance to re-provision the Thing.
4. CAUSE: The GAS instance is not configured to use SSL/TLS and the eMessage Connector is configured to use it.
ADMINISTRATOR ACTION: The configuration file of the eMessage Connector contains a configuration option, cx-server.remote-access.gas.http-client.ssl.enabled, that indicates whether, on the initiation of a remote session, the eMessage Connector should contact GAS using SSL or not. If the GAS instance is not configured to use SSL, but the eMessage Connector is configured to use SSL, the session will fail to start. An error like the one in the title of this section appears in the Application Log of the ThingWorx Platform. To resolve this issue, ensure that the Connector is configured to contact GAS, using the connection method that the GAS is configured to use (that is, use SSL or not). For assistance with this configuration, refer to Configuring the eMessage Connector. This step explains how to configure the Connector to use SSL/TLS with clients, which includes GAS instances as well as eMessage Agents.
 | Even if the configuration change resolves the connection issue on session start, you may still experience issues if the Remote Access Client is not also configured the same way. In addition, refer to Symptom: The ThingWorx Remote Access Client (RAC) fails to connect to the platform when
initiating a session for additional information. |
Symptom: Error "Unknown Connection Type: L"
CAUSE: "Listen" Type application endpoints are not currently supported.
ADMINISTRATOR ACTION: Applications associated with an agent register with either or two types of ports, Connect ("C") or Listen ("L"). The Connect type of ports are used by HTTP, SSH, and so forth. The less common usage allows the connection to operate in the opposite direction, with the client listening and the application pushing data. Such applications register with L-type ports.No solutions currently exists for the Listen port type. Where possible, choose the Connect ("C") application port type. In addition, refer to the definition of a type of connection in Storage on ThingWorx Platform .
Symptom: Error "Error communicating with GAS"
The following table lists the possible causes and actions for this error.
CAUSE | ACTION |
|---|---|
An invalid certificate for the GAS instance was presented to the SSL endpoint on the Connector. | ADMINISTRATOR: Ensure that the GAS instance has a valid certificate matching the name of the host used to connect. |
The socket to the GAS instance ended prematurely. This error may occur in the event of an unexpected interruption to the connection to a GAS instance during a session | SUPPORT: Ensure that the selected GAS instance is still reachable from the user's machine. If it is, it is possible there was a temporary network issue that lead to the socket being ended. Re-try the session. |
Symptom: Error "Unable to create local server"
CAUSE: Attempts to obtain a local port for serving a broker server have failed.
USER ACTION: Re-try the session. By default, the Remote Access Client attempts to use the port configured on the endpoint used to start the session. This endpoint is stored in the providerConfig property provided by the RemoteEndpoint Data Shape. If that port is not available, either because it is in use or is protected, the Remote Access Client will select a random port to use. This error may occur again if for some reason the random port selected is unavailable as well. Re-trying the session should cause the Remote Access Client to select a different random port. It should only ever select ports that are available, so this error should be rare, but could be caused by a race condition.
Symptom: Port configured on the eMessage agent endpoint not used for local server
CAUSE: The GAS implementation for the Remote Access Client will attempt to use same port configured on the endpoint to bind a local server, but will fall back to a random port if unable to bind a server to that port.
ADMINISTRATOR ACTION: If there is a need to ensure that the configured port is used, ensure that the user has permission to bind to that port. For example, it may be a reserved port such as SSH port 22. Also ensure that no other applications running on the user's machine are currently bound to that port.
Symptom: Connection with application client once tunnel is established fails/times out
CAUSE: The application configured to serve as the end of the tunnel is either unavailable or mis-configured.
ADMINISTRATOR ACTION: Ensure that the application with which the session is supposed to communicate is running and that the Agent configuration connects tot the correct port. Here is an annotated example of an Applications.xml from an eMessage agent project:
?xml version="1.0" standalone="yes"?>
<PersistedData moduleName= "RCon" TerseType="1">
<v>3</v>
<Application name="ssh-app" launch="auto">
<Comment></Comment>
<Hostname>$IP</Hostname>
<Port type="connect">22</Port>
</Application>
<Application name="http-app" launch="auto">
<Comment></Comment>
<Hostname>$IP</Hostname>
<Port type="connect">80</Port>
</Application>
<Application name="Desktop" launch="auto">
<Comment></Comment>
<Hostname>$IP</Hostname>
<Port type="connect">5900</Port>
</Application>
</PersistedData>
 | It is not strictly necessary that the endpoint of the application be on the same machine as the agent; In that case the Hostname property for any affected entry should also refer to a resolvable host name from the agent machine. $IP is substituted by the agent for the local host of the agent in the cases where the server application runs on the same machine, which is a typical usage. |
Symptom: Error "Error occurred. Session ended ..."
In this case, the ellipsis ("...") refers to some error message provided by the GAS instance.
CAUSE: The GAS instance has detected an error in the tunnel and has responded with an error. This message will cover any tunnel-related GAS errors
ADMINISTRATOR ACTION: Ensure that the configured ports for the endpoints match the agent's configuration. This error has been observed when the configuration given to the Remote Access Client does not match what the agent provided when it registered. This difference could be due to changes made to the configuration on the platform after the agent registered.