This topic documents the errors that can occur during the operation of the Gateway. Errors are of two main types: those which occur on a system or configuration failure and those which originate within the e-mail message itself. A few errors are reported from the SMTP Server component in the Gateway; most are reported by the Message Processor component.
All errors are recorded in the Gateway log files. All system errors can optionally be notified by means of notification triggers. The option in earlier releases to initiate an e-mail FS from the Gateway to an administrator, to report system errors, is no longer available. Errors from the message itself can be reported to the originator by specifying a script which will be processed from a worker-box FS file. This FS file will be written by the Gateway when an error occurs.
If an error relates to accessing the COPIA share and the SMTP server is able to continue to receive messages, the message processor ceases operation (a condition referred to as 'maintenance mode' below) until a check for network availability succeeds.
Start-up Errors
The Gateway settings are checked on start-up, and the start will fail if the errors listed in this section are found. The failure will be reported if the Gateway is started from GWMANAGER, and details of the failure can always be found in the Gateway trace file.
•Access to the COPIA share and FAXFACTS folder is not available
•License and configuration validation failures, including node name if configured
•Specified IP port is invalid or already in use
•Specified TLS certificate failed to load
•Specified TLS certificate supports no domain in the configured recipient domains list.
Operational Notifications
The following notifications can be enabled as triggers for a notification message in EMSETUP. EMDIRECT must be available and correctly configured on the machine running the Gateway in order to send these notifications. Each trigger can be separately enabled with specific notification recipients.
| GWOMAFAIL | The Gateway Message Processor was unable to write its OMA file. This serves as a warning that OMACHECK may report a failure although the Gateway service may be still running. |
| GWFSFAIL | Either the Gateway Message Processor was unable to obtain an FS file number to write an FS file. or it failed to write an FS file. In either case, the Gateway will enter 'maintenance mode' in which the SMTP server continues to run and save messages, but the message processor is paused. Important: in maintenance mode the SMTP server cannot continue to validate incoming messages unless the sender and recipient template folders reside on a local drive. These folders must only be moved using the Gateway Manager. |
| GWSAVEFAIL | The Gateway Message Processor failed to save an attachment file or an embedded image file from the incoming message. This error also causes the Gateway to enter 'maintenance mode' (see GWSFAIL above). |
| GWRECOVER | After retrying access to the TOSEND folders (every 5 minutes) the access has been restored and the Gateway has exited 'maintenance mode'. |
| GWMSGFAIL | The Gateway SMTP Server failed to save the MSG or MIF file for an incoming message, or the message processor failed to rename or move the message after processing. This notification normally requires immediate manual intervention; however the message folder should be local and the operations are all retried, so this error does not initiate maintenance mode. For messages collected using the built-in POP3 client, this notification is also triggered if the client fails to connect to the specified server. In this case the connection will be retried after the specified interval. |
| GWLOADFAIL | The Gateway SMTP Server failed to access the sender templates folder when searching for sender templates. This error would be expected to occur only if the GWTEMPLATES folder is on a network drive and the network becomes unavailable. |
| GWSYSTEM | The Gateway Message Processor reported one of the System Errors which does not use a specific notification trigger. These errors are shown below as items: 9, 14-17, 19, 21, 27. These errors can be individually enabled for reporting with the GWSYSTEM trigger, and it is also possible to select Message Errors in this category, which will be notified if the GWSYSTEM trigger is enabled. The selection of these items is made on the Gateway Manager tab 'Error Handling'. |
| PORTMON | This is an OMACHECK trigger, not the Gateway. It is notified when the port monitors in OMACHECK detect that an SMTP Server port is not open. |
The default settings for new installations are: "GWFSFAIL,GWSAVEFAIL,GWMSGFAIL,GWLOADFAIL,GWSYSTEM". To be notified of these errors it is necessary to configure the notification requirements in EMSETUP.
The disposition of the incoming message for these errors depends on the type of error.
•If the MSG or MIF was not saved from the SMTP server, it is lost. If not saved from the POP3 client, it remains in the mailbox.
•Otherwise, if the Gateway enters maintenance mode, the MSG and MIF remain in place to be processed after the network connectivity has been restored.
•In all other cases the MSG file and MIF are moved to the rejected messages folder.
System Errors
These errors require attention from the system administrator. The following errors will have caused the message to be rejected. Only the first detected error will be reported.
| 2 | No FS file number could be obtained. Details will be found in the trace file. This error is notified using the GWFSFAIL notification trigger. |
| 3 | Error writing FS File: Details will be found in the trace file. This error is notified using the GWFSFAIL notification trigger. |
| 9 | Message did not have a sender: This error can only occur in messages loaded from specified 'extra' folders, which will have no message information file (MIF), or if the MIF has been lost in the main 'save messages' folder, and if the From header in the message is missing or invalid. It is categorized as a system error because by definition there is no sender to whom a message error can be reported. This error is notified using the GWSYSTEM notification trigger. |
| 14 | Error loading sender template: This error occurs when a sender template cannot be loaded by the Message Processor: the load will only have be attempted if the existence of the template file was verified by the SMTP Server. This error is notified using the GWSYSTEM notification trigger. |
| 15 | Error loading recipient template: This error occurs when the template file for a special recipient cannot be loaded by the Message Processor: the load will only have be attempted if the existence of the template file was verified by the SMTP Server. This error is notified using the GWSYSTEM notification trigger. |
| 16 | Invalid decryption certificate: This error occurs when the Gateway S/MIME private key certificate cannot be loaded. This error is notified using the GWSYSTEM notification trigger. The file will also have been checked and loaded by the Gateway Manager, which checks the validity of the password. |
| 17 | No worker-box command in 'special recipient' template: This command is required. This error is notified using the GWSYSTEM notification trigger. |
| 19 | TNEF extraction failed: The Gateway Message Processor failed to decode a TNEF attachment, usually originating from a Microsoft Outlook mail client. This error is notified using the GWSYSTEM notification trigger. |
| 20 | Failed to save Attachment or embedded image: This error is notified using the GWSAVEFAIL notification trigger. If the failure occurs on an embedded image, the document may be sent without the image; if on an attachment, message will be rejected. |
| 21 | Failed to open MSG: A saved MSG file could not be opened by the Message Processor. This error is notified using the GWSYSTEM notification trigger. |
| 23 | Unhandled exception while processing message: This error is raised when an unexpected error occurs in the Message Processor. This error is notified using the GWFSFAIL notification trigger. |
| 27 | S/MIME decryption failed; cannot read encrypted message: This error can occur if there is a problem with the Gateway private keys used for decryption. The sender may be using an expired public key which the Gateway has prematurely removed after a renewed key has been added. This error is also reported as a message error because message may have been corrupted during transmission or there may be a problem with the sender's encryption process. This error is notified using the GWSYSTEM notification trigger. |
For new installations, all the above errors will be included in the GWSYSTEM trigger.
Message Errors
Each of these errors can be selected (on the Error Handling tab in GWMANAGER) to be reported to the sender, if appropriate. All are selected by default for notification, but several of those shown below are by default only warnings, and are only treated as an error when this is configured in the sender template.
The Gateway will process each of the errors normally and create an FS file as usual, except it will be marked as an error by the presence of a FORCE_FAIL variable containing the outcome code. When processed in COPIAFACTS engine the FS file will be moved to the FAIL folder. Providing Notify Errors is enabled by default or in the sender template, the normal notification will be sent to the sender, in the same way as the failure of a fax transmission. The outcome class for all the outcome codes set below is set to Z to suppress retries.
These errors result in no fax being transmitted and no worker-box actions being performed. The disposition of the incoming message depends on what error handling is specified:
•If Notify Failures is enabled for the sender, and the error number is selected in the Notify Errors to Sender section of the Error Handling tab in GWMANAGER the Gateway will rename the MSG file to BAK and leave it and the MIF in the saved messages folder.
•If Notify Failures is disabled for the sender, or the error number is not selected in the Notify Errors to Sender section of the Error Handling tab in GWMANAGER the Gateway will move the MSG file and the MIF to the rejected messages folder.
The sample script GW_ERRORS_INC.IIF can be included in a Gateway notification script to add more detail about the error message to the notification text.
The possible message errors are listed below (Error numbers 11 to 13 are no longer used) with their outcome codes:
| 1201 | No valid recipients in message: This can happen for example if the fax number was too short, or if a special recipient name was not spelled correctly. It can also occur if there was a failure to complete the processing of the only recipient in the message. This error can only be reported if the message has multiple recipients, all of which could not be processed; otherwise the specific error will be reported. |
| 1204 | S/MIME decoding failed: The signature or encryption data may have been corrupted, or the sending mail client did not encode the message correctly. |
| 1205 | S/MIME signature required but was not present: This error will only be reported if the template for the special recipient contains an $email_decrypt_keyfile command. In addition, it is only reported if you have enabled it in the sender options 'treat as an error' section; otherwise a warning will be recorded in the SMTP_WARNINGS variable and you can use this to inform the sender in the notifications sent from a secure Gateway. If access to the Gateway is limited to known users, you should not enable this as an error to avoid the need to resubmit when a signature has been accidentally omitted. |
| 1206 | S/MIME signature failed verification: There may be a problem with the sender's public key embedded in the message, or the message has been corrupted. More detail can be obtained from the SMTP_RESULT variable which is made available in notifications sent from a secure Gateway. |
| 1207 | TLS not used: This error will only be reported if you have enabled it in the sender options 'treat as an error' section. It also only applies if you have configured TLS as optional. When you configure TLS as required and a connecting client does not issue a STARTTLS command, the SMTP server will 'bounce' the message and it will not be processed. |
| 1208 | No sender password or password invalid: This error will only be reported if you have enabled a sender password in the sender options to the sender. The password text will then be required somewhere in the subject of the message. |
| 1210 | Message had an invalid sender: There is no sender template and no 'default' template to accept all senders at a domain or to accept all senders. Unless you know that this situation might sometimes arise with your designated senders, it would be unusual to report this error to an unexpected sender. |
| 1218 | Special recipient needs a valid sender template: This error can only occur if you enable it in the recipient options. It is only useful if you are running an 'open' Gateway but have some 'special recipient' named mailboxes for which a valid sender is required. |
| 1222 | Unable to parse the saved MSG file as MIME: The message structure has been corrupted and cannot be parsed as a MIME message. This is only likely to happen if a junk message is received to a domain and template validation is either disabled or allows default senders. There is little purpose in attempting to report this error to the sender. |
| 1224 | DKIM signature required but was not present: This error will only be reported if you have enabled it in the sender options 'treat as an error' section. It is intended to allow rejection of e-mails from senders who do not have 'domain key' authentication in the DNS records for their domain. This would help to reduce incoming spam, if you do not prevent spam by other means. |
| 1225 | DKIM signature failed verification: This error will only be reported if you have enabled it in the sender options 'treat as an error' section. It is intended to allow rejection of e-mails from senders who do not have valid 'domain key' authentication in the DNS records for their domain. This would help to reduce incoming spam, if you do not prevent spam by other means. |
| 1226 | S/MIME encryption required but was not present: This error will only be reported if the template for the special recipient contains an $email_decrypt_keyfile command. In addition, it is only reported if you have enabled it in the sender options 'treat as an error' section; otherwise a warning will be recorded in the SMTP_WARNINGS variable and you can use this to inform the sender in the notifications sent from a secure Gateway. If access to the Gateway is limited to known users, you should not enable this as an error: this avoids the need to re-send the message when encryption has been accidentally omitted. If you have received unencrypted e-mail, requiring it to be resubmitted in encrypted form does not repair the potential security breach which has already occurred. |
| 1227 | S/MIME decryption failed; cannot read encrypted message: The message may have been corrupted during transmission or there may be a problem with the sender's encryption process. This error is also reported as a system error because it can also be caused by a problem with the Gateway private keys. The sender may be using an expired public key which the Gateway has prematurely removed after a renewed key has been added. |
| 1228 | No message content found: The message has a valid sender and recipient which have been accepted, but no message body or useable attachments have been found in the message. |
1229 - Too many recipients: The number of To: recipients exceeds the value of GW_RECIP_LIMIT (default 1). See the detailed information about multiple recipients.
The default settings for new installations are: 1201,1204,1205,1206,1222,1226,1227,1228.
Message Warnings
A numbered warning message is saved in an SMTP_WARNINGS variable when an error occurs which has not been marked to 'treat as an error' in the associated template. Certificate validity warnings are also noted in this variable. Warning numbers are additive and more than one may be recorded for an incoming e-mail. The sample script GW_WARNINGS_INC.IIF can be included in a Gateway notification to add a more detail about the warning to the notification text.
| 1 | The incoming e-mail has not been signed but the recipient template contains an $email_decrypt_keyword, which is taken to imply a secure Gateway. For a non-secure Gateway an incoming signature will still be verified, but no warning will be issued if it is absent. The result of verification is available in the SMIME_RESULT variable. |
| 2 | The incoming e-mail has not been encrypted but the recipient template contains an $email_decrypt_keyword, which is taken to imply a secure Gateway. |
| 4 | A signing certificate which will expire in the next 14 days has been loaded from an incoming signed e-mail. This warning appears on the first use of the certificate after the service has been restarted. |
| 8 | An expired signing certificate has been loaded. This warning appears on the first use of the certificate after the service has been restarted. |
| 16 | A signing certificate could not be saved as a .CER file after loading from an incoming signed e-mail. |
