Fix Kopano Dagent “Failed to Connect to Storage Server”

When Kopano reports “Failed to Connect to Storage Server” during mail delivery, the delivery agent (dagent) could not establish a connection to the Kopano Server endpoint it was given. The message alone does not identify whether the cause is a stopped server, a wrong socket path, access permissions, or a remote connection problem. Start by checking the configured endpoint and the server itself; avoid changing mailbox data or attachment storage while diagnosing a connection failure.

Kopano’s administrator documentation describes dagent as the component that delivers mail from the mail transport agent (MTA) to a Kopano user. The Kopano Core 8.0 configuration reference says server_socket specifies the connection to the Kopano server and documents file:///var/run/kopano/server.sock as its default. Package versions, service managers, and local configuration can differ, so verify the values on your host before applying an example.

What should you check first?

Confirm whether the error affects every recipient or only one delivery path. If all incoming deliveries fail at once, check server availability and the endpoint. If only messages routed through one host or node fail, compare that node’s dagent.cfg and network path with a working node. Preserve a failed message or queue entry while testing; repeated retries can obscure the first useful timestamp in the logs.

On a system using systemd, inspect the Kopano units and the server log around the delivery time:

systemctl list-units 'kopano*'
systemctl status kopano-server --no-pager
journalctl -u kopano-server -b --no-pager

If your package names the unit differently, use the unit name shown by list-units. An inactive or repeatedly restarting server points to a server-side problem. Read its journal for an earlier startup, database, configuration, or storage error; restarting dagent will not repair an unavailable Kopano Server. The administrator manual documents Kopano service management, but exact unit names depend on packaging.

Does dagent point to the right server socket?

Read the active configuration file, usually /etc/kopano/dagent.cfg, and find the server_socket entry:

grep -nE '^[[:space:]]*server_socket[[:space:]]*=' /etc/kopano/dagent.cfg

For a local Unix socket, compare the setting with the socket actually created by the running server. A common value in Kopano Core documentation is:

server_socket = file:///var/run/kopano/server.sock

Check that the file exists and is a socket:

ls -l /var/run/kopano/server.sock
test -S /var/run/kopano/server.sock && echo "Socket exists"

If the configured and actual paths differ, correct the server_socket value to the endpoint intentionally used by your installation. Do not copy the default blindly when the server is configured to use another runtime directory, a cluster address, or a remote transport. Kopano’s reference also documents SSL key settings for HTTPS transports; remote endpoint syntax and certificate requirements should match your installed server configuration.

Could socket permissions block the connection?

Yes. A socket can exist and still be inaccessible to the user running dagent. Find the effective process user from the relevant service unit or process, then inspect the socket and every parent directory. For example:

namei -l /var/run/kopano/server.sock
stat -c '%A %U:%G %n' /var/run/kopano/server.sock

Compare the owner, group, and directory traversal permissions with dagent’s runtime identity. The Kopano dagent configuration reference notes that its run-as user and group can be configured, with Kopano as the documented default; packaging or overrides may change this. If systemd is in use, review the unit and any overrides before changing ownership:

systemctl cat kopano-dagent
systemctl show kopano-dagent -p User -p Group

Only adjust permissions to grant the intended service account the access it needs. Do not use chmod 777 on the socket or its directory: that can expose a privileged service endpoint to unrelated local users. Runtime directories may be recreated at boot, so fix the service or package configuration that creates them rather than relying on a temporary manual permission change.

What if the server is on another node?

In a multi-server or high-availability setup, verify that dagent is using the reachable cluster or server address for its node. The Kopano high-availability guide shows that service endpoints and Postfix delivery routing must be coordinated across nodes. Compare server_socket, the server listener, DNS or cluster address, firewall rules, and any TLS settings on both sides. A successful connection to a local socket on one node does not prove that a remote endpoint is reachable from another node.

Test connectivity using the same endpoint and network path configured for dagent. For a remote transport, check listener status and firewall policy on the Kopano host, then inspect the dagent and server logs for connection refusal, timeout, or TLS errors. Do not open a listener broadly to the Internet as a troubleshooting shortcut; restrict access to the trusted mail and application hosts.

How can you test delivery without changing production mail flow?

After the server is active and the endpoint and permissions agree, perform a controlled test using a designated test mailbox. The Kopano administrator manual documents invoking dagent directly with a user on that node, then entering a subject and message body. A basic test pattern is:

kopano-dagent -v -c /etc/kopano/dagent.cfg testuser
Subject: Kopano connection test

This is a controlled delivery test.
[Press Ctrl-D to finish input]

Replace testuser with an existing local Kopano user and follow your installed version’s command syntax. This test bypasses some MTA routing and queue behavior; a successful direct delivery verifies a useful part of the path, but it does not prove Postfix or another MTA is routing mail correctly. Check dagent output, Kopano logs, and the test mailbox before retrying queued production messages.

When should you restart a service?

Restart only the component whose configuration changed, and only after saving a known-good copy of its configuration. If you changed dagent.cfg, restart the dagent unit when your installation runs dagent as a persistent service. Some installations launch dagent for individual deliveries, so there may be no long-running dagent unit to restart. If you changed server.cfg or server listener settings, follow your site’s change procedure for Kopano Server instead. The dagent reference documents only selected options as reloadable by HUP; do not assume every socket or runtime-identity change takes effect through a signal.

How do you confirm the fix?

Confirm all of the following before closing the incident:

• The Kopano Server remains active without new connection-related errors in its journal.
• The endpoint configured in dagent matches a live socket or intended remote listener.
• The dagent runtime user can traverse the socket’s parent directories and access the endpoint.
• A controlled test message reaches the intended mailbox, and its logs show no storage-server connection failure.
• A new inbound message sent through the normal MTA route is accepted and delivered; the MTA queue does not continue accumulating the same failure.

If direct delivery works but mail through the MTA still fails, investigate the MTA’s LMTP transport, socket path, and routing rather than changing Kopano mailbox storage. If the server and endpoint check out but dagent still reports a connection failure, collect matching timestamps, the sanitized server_socket value, service status, and relevant logs for your package maintainer or Kopano administrator. Redact passwords, private keys, message content, and personal addresses before sharing diagnostics.

References: Kopano Core Administrator Manual; Kopano dagent configuration reference; Kopano high-availability guide; Kopano special configurations and troubleshooting.