Delivery Errors

Delivery errors occur when Modalius cannot successfully send a file to its destination. This guide explains the different error types and how to resolve them.

Delivery Error Types

Resolving Critical Errors

DNS Lookup Error

The server hostname cannot be found.

Steps to resolve:

1. Verify the server address is spelled correctly in your connection settings
2. Confirm the hostname with your partner - it may have changed
3. Check if the partner's DNS records are properly configured

Connection Timeout

The server did not respond within the allowed time.

Steps to resolve:

1. Check if your partner's server is online and operational
2. Verify there are no network issues between systems
3. Contact your partner to confirm their server is accessible
4. Retry after a few minutes - this may be a temporary issue

Connection Refused

The server actively rejected the connection attempt.

Steps to resolve:

1. Verify the port number is correct (default SFTP port is 22)
2. Check if your partner's firewall allows connections from Modalius
3. Confirm the SFTP service is running on the partner's server
4. Your IP may need to be added to the partner's allowlist

Host Key Mismatch (HOST_KEY_MISMATCH)

A HOST_KEY_MISMATCH error occurs when the SFTP server's host key no longer matches the key Modalius has on record. This typically happens when a partner migrates to a new server, reinstalls their SFTP software, or rotates their server keys.

Steps to resolve:

1. Contact your partner to confirm they intentionally changed their server key (e.g., server migration, key rotation, or software reinstall)
2. If confirmed, update the host key in your connection settings to match the partner's new key
3. If not confirmed, do not update the key - this could be a security threat and should be investigated further
4. Once the host key is updated, retry delivery for any files that failed with this error

Resolving Recoverable Errors

Authentication Failed

The username or password was rejected by the server.

Steps to resolve:

1. Verify the credentials haven't changed or expired
2. Check for extra spaces in the username or password
3. Contact your partner to confirm the business unit's SFTP credentials are still active
4. Update the credentials in your connection settings if needed

Missing Directory

The configured delivery directory doesn't exist on the server.

Steps to resolve:

1. Verify the directory path in your connection rule settings
2. Contact your partner to confirm the correct path
3. Check if the business unit has permission to access the directory
4. Update the directory path if it has changed

Connection Enable/Disable

Connections in Modalius can be enabled or disabled. Understanding this behavior helps explain why files may not be delivering as expected.

If files appear stuck in a delivering state but are not producing errors, check whether the destination connection has been temporarily disabled. A disabled connection is different from a connection error -- files are intentionally held rather than failing.

Connection Health Monitoring

Modalius monitors all connections and shows their health status:

Automatic Recovery

When a connection becomes unreachable, Modalius automatically:

• Queues files - Files waiting for delivery are held until the connection recovers
• Tests periodically - The system automatically tests the connection until it recovers
• Releases queued files - When the connection recovers, queued files are automatically delivered
• Notifies you - You'll receive notifications about connection issues and recovery