Investigate in a consistent order

  1. In Data Bridge, open Settings → Access → Agents and select the Agent. Record its status, the incident time, the last disconnection reason and the relevant log entry.
  2. On the Agent computer, open local settings and Status. Check that the service is running and the computer is awake.
  3. Open Diagnostics → Run diagnostics. Resolve the first significant failure on the route to Data Bridge.
  4. After restoring the channel, select Test connection for the resource and Test on the Data Bridge connection.

Diagnostics run as the service account. Opening an API in your browser does not prove that the service has the same proxy, certificates or permissions. Standard checks do not change data; a folder write test requires separate confirmation.

Registration and access states

  • Awaiting registration. Enter the single-use key locally. Select Issue new key if it was lost, used or expired.
  • Awaiting approval. Compare the local and Data Bridge codes. Operations become available after approving an exact match.
  • Active, offline. Check the service, power and network. Active authorization alone does not mean the Agent is connected.
  • Disabled. An administrator selects Enable; no new key is required.
  • Access revoked. Establish why access was revoked, then obtain a new key for an authorized registration.
  • Access expired. An administrator extends the access period in Data Bridge.

AGENT_MACHINE_CHANGED indicates a mismatch with the registered computer. For a planned move, register the new computer with a new key; do not copy the state directory. If no move was planned, review the log and revoke access if appropriate. After registration attempts are temporarily blocked, wait 15 minutes and check that the key is correct.

Networking, proxy and TLS

Diagnostics check settings, proxy, DNS, TCP 443, TLS and gateway, clock, registration, transport and secure channel. Follow the recommendation beside the first failed step. When the proxy resolves external hostnames, a DNS warning alone does not indicate failure.

If TCP 443 is blocked, arrange outbound access to Data Bridge or configure the proxy. For blocked WebSockets, keep automatic mode or select HTTPS requests manually. For an untrusted certificate, add an approved root PEM readable by the service; do not disable TLS verification. If the gateway is missing, check the installation address and agent/v1/ route with the administrator.

Inspect the Windows system proxy with netsh winhttp show proxy, or macOS proxy settings with scutil --proxy. Synchronize the clock through operating system settings. See the network configuration guide for further settings. On Linux, check the proxy settings available to the Agent service itself; see network preparation.

A resource cannot be reached

AGENT_POLICY_DENIED means the host, port or folder does not match an allowed resource. Compare the exact connection values with the local policy. AGENT_RIGHTS_DENIED identifies a prohibited API method or file operation; also inspect folder permissions in the Data Bridge connection.

For AGENT_DNS_FAILED, check name resolution on the Agent computer. AGENT_CONNECT_REFUSED often means the target service is not listening on that port. For AGENT_CONNECT_TIMEOUT or AGENT_UNREACHABLE, inspect routing and firewall rules. AGENT_TLS_CERTIFICATE concerns the resource certificate’s trust, not database account privileges.

AGENT_ACCESS_DENIED is an operating system denial. Grant permissions to the service account itself. For UNC paths, check both share and NTFS access; on macOS, inspect system mounts and required privacy permissions. Follow the specific Windows or macOS instructions. For Linux, also check service-account permissions, network mounts and SELinux or AppArmor rules in the resource access guide.

File errors and safe retries

For AGENT_PATH_OUTSIDE, use a path inside the allowed folder without traversal or external links. For AGENT_NOT_FOUND, check the path and masks. AGENT_CHANGED indicates a concurrent file change; retry after that change finishes. With AGENT_INTEGRITY_FAILED, the file was not written because its size or SHA-256 did not match; investigate transfer stability.

For WRITE_OUTCOME_UNKNOWN, inspect the destination folder first. The channel disconnected after data was sent, so the write may have completed. Do not automatically repeat it before checking the result. For AGENT_TOO_LARGE, AGENT_DISK_FULL and AGENT_BUSY, inspect limits, free storage and workload respectively. Assess capacity before increasing limits.

Installation and update failures

For installation failures, read the installation log and address the stated system requirement. Obtain a damaged package again from the administrator and verify its SHA-256. If installation succeeded but registration did not, complete registration in the local Connection tab.

Under Version and updates, inspect the outcome: successful, failed, rolled back or rejected. Do not install a package with an untrusted signature; contact the supplier. After rollback, review agent.log, fix the cause and retry the update. AGENT_OPERATION_UNKNOWN may require an Agent update; AGENT_HUB_UNAVAILABLE calls for another check after the gateway recovers.

Prepare a useful support report

Copy the diagnostic report, the last 200 lines of agent.log and the relevant time window from audit.log. Include the Agent name, Agent and operating system versions, incident time and run identifier if known. Windows logs are under C:\ProgramData\UBC Data Bridge Agent\logs\; macOS logs are under /Library/Logs/UBC Data Bridge Agent/. On Linux, the log location depends on the installed package. Confirm it with your administrator and follow the maintenance guide.

Review filenames, usernames and internal system names before sharing logs. Never send the registration key, state files or secrets.json. After fixing the problem, repeat diagnostics, the resource test and a controlled run, then confirm that the operation produced the intended result.