Troubleshooting

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), we recommend 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.

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.

How do I update the Relay client binary?

Download the new binary and run relay restart <id>. The restart command detects the updated binary and applies the change without requiring a full reinstall.

What data does the Relay client store on disk?

Encrypted client configuration, proxy configuration fetched from the cloud, and log files. No application data is written to disk — the Relay client streams 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.

I added a new endpoint in UiPath Administration — do I need to restart the Relay client?

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 blocking outbound TCP to the relay server; the pre-flight connectivity check cannot complete the TCP handshake	Allow outbound TCP to <region>-relay.uipath.com:443 from the relay node
TLS handshake errors, connection reset, or recurring unexpected EOF after the TCP connection succeeds	TLS-inspecting proxy, DLP, or IDS appliance is intercepting the session to the relay server (TLS passthrough is required)	Configure your proxy or firewall to bypass TLS inspection for <region>-relay.uipath.com:443. The pre-flight check passes because TCP is reachable — the break appears only once the relay attempts the TLS handshake
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: common after VM clone or reimage — re-provision the relay. Re-provision indicates 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

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/2] Relay metadata and configuration... (2 groups)
  [2/2] Relay logs...

✓ 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 log files
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)
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.