Errors

They are a part of life when coding. They happen in every project, and thus they should be as descriptive as possible.

ImapError

cf-imap throws a descriptive ImapError whenever the IMAP server responds to a command with an error status (NO or BAD). It is an Error subclass with a few extra properties:

import { CFImap, ImapError } from "cf-imap"

try {
    await imap.connect()
} catch (e) {
    if (e instanceof ImapError) {
        console.log(e.status)        // "NO" | "BAD"
        console.log(e.tag)           // the command tag, e.g. "A1"
        console.log(e.messageText)   // the server's error message, e.g. "Login failed"
        console.log(e.untagged)      // the raw untagged response items received before the error
    }
}

Property	Type	Description
status	"NO" \| "BAD"	The status code of the tagged response.
tag	string	The command tag the error belongs to.
messageText	string	The human-readable message from the server.
untagged	{ line: string, literal?: Uint8Array }[]	The raw untagged response items received before the error — great for debugging.

Other errors

Non-protocol failures throw regular Errors:

• Read timeouts — IMAP read timed out after Xms (configurable via the timeoutMs option). Exception: during idle() a timeout is a clean exit (see IDLE) — it ends IDLE without closing the connection instead of throwing.
• Connection drops — IMAP connection closed by server.
• Usage mistakes — e.g. running a command before connect() or before selecting a folder.
• LOGINDISABLED — connect() refuses to send LOGIN when the server advertises LOGINDISABLED and no AUTH=PLAIN is available (RFC 9051 §6.2.3).
• Concurrent commands — only one IMAP command may be in flight at a time; issuing a second one (including during idle()) throws Another IMAP command is already in progress....
• check() on IMAP4rev2 — CHECK was removed from RFC 9051, so check() throws on rev2 sessions.

If you believe something that should work is throwing an error, raise an issue on GitHub and include the error message along with e.untagged / the cause of the error.