Once running, the Agent is designed to operate continuously without supervision. The Agent is designed to automatically reestablish connectivity whenever a temporary connection issue occurs. However, connectivity is ultimately controlled by the underlying operating system so connectivity issues on the operating system will also affect the Agent.

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
• Agent has been stopped
• Windows Services issues
• Operating System (OS) connectivity
• Buffer Size Warning Message

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.

Network Locations for the Root Setting

If the root setting has been configured to a network location, then make sure that the location path is valid and that the Agent user account, or service account, has the correct access permissions to the network location.

On Windows based systems, ensure that UNC paths are used instead of mapped network drive paths. Microsoft recommends the use of UNC paths for system services.

To determine access permission issues, try setting the root to a local path first. Ensure that the Agent starts up and can be used from your Files.com site. Test access to the network location using the system file browser, making sure that you are logged in as the Agent user or service account. If access to the network location is successful from the system file manager, verify the exact path being used and use it for the root setting.

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.

Agent Stopped

Ensure that the Agent is running and that it hasn't been manually stopped.

If the Agent has been installed as a system service then the Agent will automatically restart when the system is booted or rebooted.

Check that the system service hasn't been been manually stopped or uninstalled.

Once running, the Agent is designed to operate continuously without supervision. The Agent should only stop if it has been manually stopped or if the system service that controls it is stopped.

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.

Operating System (OS) Connectivity

The Agent uses the underlying operating system (OS) for connectivity with Files.com and any local network storage.

Ensure that the host system is connected to the internet so that the Agent can connect with your Files.com site.

Ensure that any network attached storage locations (CIFS, SMB, NFS, etc.) that you want the Agent to interact with can be reached, and interacted with, using the underlying operating system.

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...".