Error Handling
Error Handling is the set of rules on a node that determine what happens to an item the node could not process. Every node after the trigger has an Error Handling section and an Error path. A rule matches an error type and sets an action, Continue or Propagate. Automations perform operations that cannot be undone, including moving, deleting, and sending files, so every failure has a type, and the rules on a node are where you choose, by type, whether the failed item continues or the run fails.
A failure affects one item. When a node cannot process one of the 40 files it received, the other 39 continue through the node and on to the next one, and the failed item retains its original input, with the status Failed and its error type. What happens to the failed item is determined by the node's rules. Retry Handling, which starts a new run after a failed run, is compared in Error Handling vs. Retry Handling below.
Error Types
Every failure has an error type. The type names one of three families and can name a specific error within the family, written as family/specific-error.
| Family | Meaning |
|---|---|
not-found | A required item or referenced resource no longer exists. A file that another branch moved or deleted before this node read it fails with this type. |
processing-failure | The node could not process the item. A destination that already exists with overwriting off is processing-failure/destination-exists, a Transform script that fails is processing-failure/transform-error, an AS2 delivery that fails is processing-failure/as2-delivery, and Send Email attachments over 25 MB are processing-failure/attachment-too-large. |
service-unavailable | A required remote service is temporarily unavailable. A Remote Server that cannot be connected to is service-unavailable/remote-connection. |
A rule's Error Match is one of the three families or *, which matches every error. A family matches every specific error in it, so a rule on service-unavailable matches every remote service failure without naming each one. In the JSON definition and the API, a rule can also name a specific error, for example processing-failure/destination-exists, so that Continue applies to an existing destination while every other processing failure stops the path.
Rules on a Node
Each rule pairs an Error Match with an Action. Rules are checked in the order they are listed, and the first rule that matches the error applies. An error that no rule matches stops the item on this path. Rules are optional, and a node with no rules stops every failed item on its path.
Order the rules from the most specific match to the most general. A rule on not-found set to Propagate above a rule on * set to Continue stops the path for a missing file and applies Continue to every other error.
Continue and the Error Path
Continue treats the error as handled. The failed item is routed to the node's Error path when a node is connected there, and the run continues. Connect the nodes that process failed items to the Error path the same way you connect a branch. A Move File node on the Error path of an Encrypt With GPG node moves each file that could not be encrypted to a quarantine folder, and a Send Email node on the Error path of a Send via AS2 node sends one email for each delivery that failed. When nothing is connected to the Error path, a failed item that a Continue rule matched is not processed further, and the run still continues.
The items on the Error path are the failed items themselves, with the same file reference or data they had when the node received them, so a node on the Error path can move, copy, or report on the original.
Propagate and Run Status
Propagate treats the error as unhandled. The failed item is not processed further on this path, and the run finishes with the status Failure. When the node belongs to an Automation that a Run Automation node ran, the error is matched against that node's rules instead, and its action determines whether the calling run fails. An error that no rule matches has the same result.
A run whose failures were all handled by Continue rules finishes as Partial Failure. The other items in the run are processed to the end in every case, so a run that finishes as Failure can still have delivered every file except the one that failed. Retry Handling can start a new run after a Failure or Partial Failure, resuming at the failed node.
Files.com also rejects a graph that fails validation when you save it. Save-time validation has its own error codes, and Error Handling rules do not match them.
Error Handling vs. Retry Handling
Error Handling determines, during a run, what happens to an item a node could not process. Retry Handling determines, after a run has finished as Failure or Partial Failure, whether Files.com starts a new run that resumes at the failed node. Actions also retry certain errors up to three times within a run before the item counts as failed. Use Error Handling to route failed items to nodes that move them to a quarantine folder or send a notification. Use Retry Handling for failures that a later run can complete, for example a Remote Server that is temporarily unreachable.