Most of the time, Files.com Agent connection issues are caused by one of the following things:

• Incorrect configuration of the Agent
• System that the Agent is installed on is offline or powered off
• Clock (time and date) is incorrect on the host system
• Windows Services issues

Configuration

The only component of the configuration file that needs to be updated is the value for "root".

Check that the Agent's configuration file has no typos or syntax errors. The file must contain valid TOML syntax, where all values are enclosed in double-quotes.

The most common TOML syntax error is using Windows slashes instead of Linux slashes in folder paths that are enclosed within double-quotes. When setting the root value, use single quotes to enclose the value.

For example, a correctly configured "root" setting should look like this:

root = 'C:\Users\Agent'

If you try to start the Agent with an invalid "root" setting in the configuration file then you'll see an output message like this:

root is missing from config. {"root": "/path/to/root"} - /path/to/files_agent_config.toml

Edit the configuration file, set the "root" value correctly, and then re-start the Agent.

Agent Offline

Ensure that the system that the Agent is installed on is powered on and online. When the system is down or offline then you may see the following effects:

• Remote Mount folders will not function.
• Remote Sync will temporarily fail.

Remote Mount Issues

If the system, and Agent, cannot be reached then any Remote Mount folders will not be accessible and cannot be interacted with by users or Automations.

Remote Sync Issues

If the system, and Agent, cannot be reached then any Remote Sync will fail until the Agent is accessible again. Once the Agent is accessible again, subsequent syncs will then resume and succeed.

Invalid Access Token Issues

The Agent uses secure access tokens to communicate with Files.com. These tokens are automatically generated as needed but are only valid for short durations.

The most common issue that causes a token to become invalid is when the system clock isn't accurate or has drifted in time. An example error message for this is:

invalid acces token token used before issued

Correct the data and time on the system that the Agent is running on. We strongly recommend configuring the system to use Network Time Protocol (NTP) so that its clock remains accurate.

Windows Services Issues

Error 1053: The services did not respond to the start or control request in a timely fashion.

This error occurs when the service cannot find the Agent configuration file. When installing the Agent Service using the command line, make sure that you include the full path to the configuration file. For example, use files-agent service install --config C:\path\to\files_agent_config.toml instead of files-agent service install --config files_agent_config.toml.

Uninstall the service then re-install using the correct path to the configuration file, or use the MSI to install the service instead.

Service 'Files Agent v2' (file-agent) could not be installed. Verify that you have sufficient privileges to install system services.

This error occurs when you attempt to re-install the service but the previous service has not been fully uninstalled.

Make sure you use the Windows "Add or remove programs" app to remove the Agent prior to re-installing the service.

Windows will not fully uninstall a service if apps such as Services and Task Manager are open. Instead the service is placed into a disabled state. Close all Services and Task Manager apps then re-open the Services app to verify that the Agent entry is no longer listed. If you cannot determine which open app is keeping the service in a disabled state then rebooting should solve the issue.

Buffer Size Warning Messages

When starting the Agent, you may see the following warning message about failing to increase the receive buffer size:

2024/02/16 17:19:13 failed to sufficiently increase receive buffer size (was: 208 kiB, wanted: 2048 kiB, got: 416 kiB). See https://github.com/quic-go/quic-go/wiki/UDP-Buffer-Sizes for details.

This message is for information only and does not affect the Agent. This message occurs when the Agent is trying to establish the fastest possible UDP connection but the operating system can only provide a lower, yet still fast, speed.

Troubleshooting Steps

Always run the Agent manually first, to check functionality and connectivity, prior to installing it as a system service. If the Agent works when run manually, but does not when run as a system service, then compare the permissions between the account that was used to manually run the agent and system service account.

Check the Agent status, as shown in the Remote Server entry for your Agent. When the Agent sends a heartbeat back to Files.com then this status will change from "Waiting for connection..." to "Connected." The "Connected" status confirms that the Agent has been able to "call home" and connect back to your Files.com site through your firewall.

When the Agent is shut down normally, such as by using CTRL+C when running the Agent manually or by shutting down or rebooting the system when the Agent is running as a system Service, the Agent status will change back to "Waiting for connection...".