Troubleshooting

Known issues and answers to common questions about Relay connectivity, DNS configuration, and Cloudflare DDoS protection.

Frequently asked questions

Does Relay protect against DDoS attacks?

The Relay domain is an additional DNS record under uipath.com, served through Cloudflare. DDoS protection is handled by Cloudflare, consistent with how cloud.uipath.com is protected.

Do all Relay clients need to be deployed in the same region?

No. Relay clients connect to the Relay API through the standard routing layer regardless of where they are physically deployed. However, for best performance, especially for large-payload scenarios such as BYO LLM, deploy the Relay client in the same geographic region as your Automation Cloud tenant. Cross-region tunnels add latency proportional to the round-trip time between the regions.

What are the latency expectations?

Latency and throughput depend on payload size, the geographic distance between the relay node and the Relay Server, and the capacity of the relay node. Same-region deployments add minimal overhead. Cross-region tunnels add latency proportional to the network round-trip time between the regions.

What happens if the Relay client loses connectivity?

The Relay client reconnects automatically using exponential backoff, scaling to 20-second intervals. The background service restarts automatically on crash and on system reboot. No manual intervention is required for transient network issues. For persistent disconnections caused by idle-connection timeouts on network appliances, enable proactive reconnect. See Deploying the Relay client.

Do we need different relay nodes for different tenants?

No. The same relay node can run the Relay client process for multiple tenants simultaneously.

When do we need to create multiple relay groups?

Multiple relay groups are recommended only for network segregation. For example, if you have Jira in Network 1 and SAP in Network 2, you can create two relay groups with Jira in one and SAP endpoint in the other. You can run the relay client processes for these groups in two VMs which have access to the respective networks.

Is there any limit on the number of on-premises endpoints per relay group?

There are no hard limits. With moderate traffic (1–10 requests per second per endpoint), use up to 50 endpoints per group. With lower traffic, up to 100 endpoints per group is supported.

Can I run multiple Relay clients on the same machine?

Yes. Each relay group gets its own background service, data directory, and log directory. Use relay list to see all installed Relay clients and their status. Use relay describe <id> to inspect the service settings and local paths for a specific Relay client.

Can I move a Relay client to a different machine?

No. Credentials are encrypted with machine-specific keys: AES-256-GCM on Linux, DPAPI on Windows. To move, delete the Relay client on the old machine and re-provision on the new machine with a fresh configuration from UiPath Administration.

What happens if I clone a VM that has a Relay client installed?

Credential decryption fails on the clone because the machine identity differs. Run relay delete <id> --force on the clone and re-provision with a fresh configuration.

Can I rotate the credentials used by the Relay client?

Yes. Generate a new configuration from the Setup instructions page. A new secret is created each time the configuration is generated. Relay limits how many secrets you can generate. If you reach the limit, identify the secret ID in use by your clients, either on the Relay Groups page or by running relay describe <id> on the client, then delete the unused secrets from the External Applications page by searching for the group ID.

How do I update the Relay client binary?

Extract the new archive and run relay restart <id> from the extracted directory. The restart command detects the updated binary and applies the change without requiring a full reinstall. If the on-prem executor is enabled, running from the extracted directory also updates onprem-executor.jar.

What data does the Relay client store on disk?

Encrypted client configuration, proxy configuration fetched from the cloud, and log files. When the on-prem executor is enabled, the Relay client also stores onprem-executor.jar and onprem-executor.log. No application data is written to disk. The Relay client and the executor stream traffic in memory.

Can I change the proxy configuration after the Relay client is installed?

Yes. Update the proxy environment variable and run relay restart <id> to apply the change.

Why does my proxy require credentials but the Relay client connects without them?

The environment variable is likely not being passed to the background service. On Linux: re-run with sudo -E or run relay restart <id>. On Windows: set the proxy at system level (HKLM) rather than in the user environment.

Do I need to restart the Relay client after adding an endpoint in UiPath Administration?

No. Configuration changes are pushed automatically to a running Relay client without dropping in-flight connections. If the newly added endpoint returns 404, the push has not yet been applied. Run relay reload <id> as a fallback.

Common issues

If the issue below does not resolve your problem, collect a support bundle and contact UiPath support.

Symptom	Cause	Resolution
cloud portal unreachable	Firewall blocking port 443	Allow outbound HTTPS to cloud.uipath.com:443
authentication failed	Invalid or expired credentials	Regenerate the client configuration from the Relay Group in UiPath Administration
relay server unreachable	Firewall or proxy blocking the persistent tunnel	For Relay client 26.4.2 configurations that connect through cloud.uipath.com, allow HTTPS traffic and WebSocket upgrades to cloud.uipath.com:443. For Relay client versions earlier than 26.4.2, allow outbound TLS to <region>-relay.uipath.com:443 from the relay node
TLS handshake errors, connection reset, or recurring unexpected EOF after initial connectivity succeeds	TLS inspection uses an untrusted signing CA, a proxy blocks WebSocket upgrades, or a DLP/IDS appliance interrupts the tunnel	For Relay client 26.4.2 configurations that connect through cloud.uipath.com, allow WebSocket upgrades to cloud.uipath.com:443 and install any TLS inspection signing CA in the OS trust store used by the Relay client. For Relay client versions earlier than 26.4.2, configure your proxy or firewall to bypass TLS inspection for <region>-relay.uipath.com:443. The pre-flight check passes because the destination is reachable; the break appears only once the relay attempts to establish the tunnel
provisioning timed out after 60s	Network latency or proxy delay	Check connectivity and proxy settings; retry
maximum number of allowed agents	Group has reached its Relay client limit	Delete unused Relay clients from the group, or create a new Relay Group
config input is empty	Empty --config value or empty config file	Verify the config string or file is not empty
relay is already running	Duplicate relay start for a group whose service is already active	Run relay stop <id>, then relay restart <id>
relay for group "<id>" is already installed as a system service	A Relay client for this group is already installed on the machine	Run relay delete <id>, then reinstall
ID mismatch on restart	Config file belongs to a different group	Verify you are using the correct config file for the relay ID
credentials: decryption failed	AES key file missing or corrupted (Linux), or DPAPI identity changed (Windows)	Linux: if the key file was deleted, re-provision the relay. Windows: re-provision the relay, which is common after a VM clone or reimage. To re-provision, run relay delete <id> followed by relay start with the new configuration
Deregistration fails on delete	Credentials lost or cloud-side objects already deleted	Use relay delete <id> --force to skip cloud deregistration
host unreachable via proxy	Proxy cannot reach the target	Verify the proxy URL is correct; check proxy logs; confirm the proxy allows CONNECT to port 443
cannot reach proxy	Proxy address is unreachable	Verify the proxy host and port are correct and reachable from the relay node
proxy CONNECT rejected (407)	Proxy requires authentication	Add credentials to the proxy URL: http://user:password@proxy:port
Proxy environment variable set but relay connects directly	Environment variable not passed to the service	Linux: re-run with sudo -E or run relay restart <id>. Windows: set the proxy at system level (HKLM)
Relay reconnecting repeatedly	Unstable network or silent idle-connection timeout	Check connectivity; consider enabling proactive reconnect
Relay client cannot reach on-premises endpoint	Relay client machine lacks network access to the target	Confirm the relay node has direct network access to the on-premises endpoint
TLS error connecting to on-premises endpoint	CA certificate not trusted by the relay node's OS trust store	Add the issuing CA certificate to the relay node's OS trust store
local error: tls: no renegotiation when calling an HTTPS on-premises endpoint	The backend server or load balancer requests TLS renegotiation after the initial handshake	Disable TLS renegotiation on the backend or use TLS 1.3. If the backend cannot be changed, contact UiPath Support for approval before using the temporary TLS renegotiation workaround.

On-prem executor issues

These issues apply to supported TCP-based connections that use the on-prem executor.

Symptom	Cause	Resolution
java executable not found, unsupported Java version, or Java version check failed	A supported TCP-based connection uses the on-prem executor, but Java is missing, too old, or not available to the Relay service account	Install a Java 21 or later JRE or JDK and make sure java is on the service account PATH, or pass --onprem-executor-java-home <java-home>
bundled on-prem executor runtime was not found next to the relay binary	onprem-executor.jar is missing, unreadable, or not a valid JAR file	Extract the Relay binary and onprem-executor.jar from the same archive and keep them together when starting or upgrading the service. Run relay describe <id> to check the reported executor version
UiPath Relay On-Prem Executor cannot listen on localhost:<port> or --onprem-executor-listen-port must be between 1 and 65535	The configured loopback port is already in use or outside the valid TCP port range	Choose a free local port with --onprem-executor-listen-port <port>. The default is 18080
On-prem executor starts but the TCP-based connection fails	The Relay host cannot resolve or reach the target system, or the connector libraries are missing	Check onprem-executor.log, verify target hostname and port access from the Relay host, and confirm the connector libraries are in the dependencies directory
--onprem-executor-dep-dir path is not accessible, must point to a directory, or must not be group- or world-writable	The path does not exist, is not a directory, or is group- or world-writable on Linux	Point --onprem-executor-dep-dir at an existing administrator-owned directory that the Relay service account can read and unprivileged users cannot modify
UnsatisfiedLinkError and libsapjco3.so: cannot open shared object file in the executor log, even though the file is present	The SAP JCo native library does not match the operating system and CPU architecture of the process loading it	Download the SAP Java Connector 3.1 package for the correct platform: the Relay host for a service deployment, or Linux on x86_64 for the container image. Confirm with file libsapjco3.so

Use the TLS renegotiation workaround temporarily

Relay disables server-requested TLS renegotiation by default. If UiPath Support approves the workaround:

1. Set UIPATH_RELAY_ALLOW_TLS_RENEGOTIATION=once in the Relay client service environment:

   Linux system service: Run sudo systemctl edit relay-<id>.service, then add and save:

   [Service]
   Environment="UIPATH_RELAY_ALLOW_TLS_RENEGOTIATION=once"
   

   On a host without an interactive editor, write the same block to /etc/systemd/system/relay-<id>.service.d/override.conf and run sudo systemctl daemon-reload.

   Linux user-mode service: Run systemctl --user edit relay-<id>.service and add the same block.

   Windows: In Administrator PowerShell, run:

   [Environment]::SetEnvironmentVariable("UIPATH_RELAY_ALLOW_TLS_RENEGOTIATION", "once", "Machine")
   

2. Restart the Relay client service:

   Linux system service:

   sudo relay restart <id>
   

   Linux user-mode service:

   relay restart <id>
   

   The systemctl edit command reloads the unit configuration after you save the override.

   Windows:

   .\relay.exe restart <id>
   

   Note:

   The value once allows a single renegotiation per connection. Use freely, which allows repeated renegotiation, only if UiPath Support determines that the backend requires it.

3. After the backend is updated, remove the environment setting and restart the Relay client service:

   Linux system service: Run sudo systemctl edit relay-<id>.service, remove the environment setting, then run the Linux system-service restart commands from step 2.

   Linux user-mode service: Run systemctl --user edit relay-<id>.service, remove the environment setting, then run the Linux user-mode restart commands from step 2.

   Windows:

   [Environment]::SetEnvironmentVariable("UIPATH_RELAY_ALLOW_TLS_RENEGOTIATION", $null, "Machine")
   .\relay.exe restart <id>
   

Collect a support bundle

If none of the issues or solutions described in this page apply to your scenario, report the issue to UiPath support by collecting a support bundle, a compressed archive containing configuration, logs, and system details needed for diagnosis. Credentials and encryption keys are never included.

# Collect for all relay clients on this machine
relay support-bundle

# Collect for a specific relay client
relay support-bundle <id>

# Write to a specific directory
relay support-bundle --output-dir /path/to/dir

The archive is written to the current directory by default (.tar.gz on Linux, .zip on Windows). Share the archive and its SHA-256 hash with UiPath support.

Sample output:

Collecting support bundle...
  [1/3] Relay metadata and configuration... (2 groups)
  [2/3] Relay logs...
  [3/3] System diagnostics...

✓ Support bundle created: support-bundle-relay01-20260413-150405.tar.gz (3.1 MiB)
  SHA256: a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789

What's included

File	Contents
bundle-info.json	Bundle metadata: relay version, hostname, OS, architecture, collection time
relay-version.txt	Relay version, build date, and git commit
relay-list.json	All relay groups on this machine with status
groups/<id>/data/	Per-group metadata (metadata.json)
groups/<id>/logs/	Per-group Relay client logs, including onprem-executor.log when the on-prem executor is enabled
groups/<id>/onprem-executor.txt	On-prem executor status and diagnostic metadata, including Java and runtime information and configured dependency filenames and sizes (present only when the on-prem executor is enabled)
errors.log	Non-fatal collection warnings (present only if warnings occurred)

What's excluded

Excluded	Reason
client_config	Contains encrypted client credentials
*.key files	AES encryption keys (Linux only)
*.jar files	Keeps runtime and dependency binaries out of the archive; relevant metadata is included in onprem-executor.txt instead
Symlinks	Prevents path traversal outside the bundle

Note:

Linux: Groups installed as system services require sudo relay support-bundle. User-mode groups do not. If the command skips a group with a permission warning, re-run with sudo.