Errors
Every error @node-net/netconf throws when a call fails is a NetconfError, whichever layer it comes from, whichever entry point you imported it from, and whether you called client.ops or client.content. That includes YANG data errors from JSON conversion. A bug in the calling code is the exception: see Programming errors. Each has a stable code (such as ERR_NETCONF_RPC) and, where there is one, a cause. A client.content.read() can fail with a HostKeyError, a TimeoutError or an RpcError just as client.ops.getConfig() can.
import { NetconfError } from '@node-net/netconf';
// The lab's interfaces have no mtu
const IF = '/ietf-interfaces:interfaces/interface[name="eth0"]';
try {
await client.content.set(`${IF}/mtu`, 9000);
} catch (err) {
if (!(err instanceof NetconfError)) throw err;
// ERR_NETCONF_TRANSACTION Transaction failed at edit: …
console.log(err.code, err.message);
}By layer
The classes are grouped here by the RFC 6241 layer they come from:
NetconfError
│
│ === TRANSPORT ===
├─ TransportError connecting or keeping the connection failed (DNS, TCP, SSH or TLS)
│ ├─ AuthenticationError .reason: 'refused', our own 'key' unusable, or a 'prompt' unanswered
│ ├─ HostKeyError host key doesn't match, or no host-key policy given
│ └─ CertificateError TLS server certificate not trusted, wrong name, or pin mismatch
├─ FramingError broken RFC 6242 framing or a size limit; the session closes
│
│ === MESSAGES ===
├─ XmlError malformed XML, a DOCTYPE, or a parser limit exceeded
├─ HelloError a bad hello, or no common base version
├─ SessionClosedError the session closed while waiting; .cause says why
├─ ProtocolError the server broke the protocol: an unexpected or unmatched message
│ └─ BaseNotificationError a base notification that breaks ietf-netconf-notifications
│
│ === OPERATIONS ===
├─ RpcError the server replied with <rpc-error>
├─ CapabilityError the server didn't advertise what the operation needs
├─ SubscriptionError a subscription can't be created
│ └─ SubscriptionOverflowError the notification queue overflowed
│
│ === CONTENT ===
├─ PathError a path that can't be parsed, or names an unknown module
├─ SchemaUnavailableError no YANG schema for the data (requireSchema), or none by that name
├─ YangDataError YANG data that doesn't match the schema; .issues lists each problem
├─ TransactionError a candidate transaction failed; .phase says where
│ └─ LockDeniedError another session holds the lock
│ └─ PartialLockDeniedError another session holds a lock on some of the same nodes
│
│ === ANY LAYER ===
├─ TimeoutError .phase: connect, hello, rpc or close
├─ AbortError your AbortSignal fired; .cause is its reason
│
│ === SETUP ===
└─ ProfileError a device profile file is invalidJSON data that doesn't match the YANG schema is refused with a YangDataError.
RpcError
An RpcError holds every <rpc-error> in the reply. err.first is the first, and err.tag its tag:
import { RpcError, x } from '@node-net/netconf';
const IF = 'urn:ietf:params:xml:ns:yang:ietf-interfaces';
const config = x('interfaces', { xmlns: IF },
x('interface', x('name', 'eth0'), x('enabled', 'maybe')),
);
try {
await client.ops.editConfig({ target: 'running', config });
} catch (err) {
if (!(err instanceof RpcError)) throw err;
for (const e of err.errors) {
// invalid-value application /ietf-interfaces:interfaces/…
console.log(e.tag, e.type, e.path, e.message, e.appTag);
}
if (err.tag === 'access-denied') { /* NACM refused it */ }
}path is an XPath whose prefixes are the server's. They resolve with the declarations in scope on the error's element (RFC 6241 §4.3), including any the server declared on <rpc-reply>: e.element.lookupNamespace(prefix).
tag is typed as the RFC 6241 error tags, so your editor can autocomplete them, but it also accepts any string a server sends. info holds the <error-info> element, and err.reply the whole <rpc-reply>. Errors with severity warning in a reply that otherwise succeeded don't throw. They arrive as a 'warning' event on client.session.
An RpcError is often the cause of a higher-level error, such as a TransactionError from client.content.set().
TransactionError and LockDeniedError
withCandidate(), and the Content layer calls built on it such as set() and configure(), reject with a TransactionError:
phase: where it failed:lock,discard,edit,validate,commit,confirmorcancelcause: the original error, such as anRpcErrorcleanupErrors: anything that went wrong while discarding or unlocking. These never replace the original error.
If another session holds a lock, the error is a LockDeniedError, with the datastore and the holder's session-id (0 means something other than a NETCONF session holds it). A refused partial lock is a PartialLockDeniedError, which adds the conflicting lockId if the server gave one. A plain client.ops.lock() that is refused rejects with an RpcError whose tag is lock-denied.
TimeoutError and AbortError
A TimeoutError's phase says what didn't finish in time: connect, hello, rpc or close. Set the limits as described in Connecting, or per call with { timeout }. Every request also takes { signal }; when the signal fires, the call rejects with an AbortError whose cause is the signal's reason.
YangDataError
JSON is checked against the server's YANG schema first, and data that doesn't match is never sent (Mistakes). The call rejects with a YangDataError, whose issues list every problem, not only the first: each has a code (such as unknown-node, invalid-value or missing-key), a message and the RFC 7951 data path it applies to. The same error is thrown when a JSON read with requireSchema gets data that doesn't match the schema. Its cause is the error from @node-net/yang, the YANG library that does the checking.
import { YangDataError } from '@node-net/netconf';
// ietf-system has no colour
const json = { 'ietf-system:system': { colour: 'blue' } };
try {
await client.ops.editConfig({ target: 'candidate', config: json });
} catch (err) {
if (!(err instanceof YangDataError)) throw err;
// /ietf-system:system/colour unknown-node the schema has no node …
for (const i of err.issues) console.log(i.path, i.code, i.message);
}Connection failures
TransportError and its subclasses come from connect(). An AuthenticationError's reason is 'refused' when the server rejected the credentials, 'key' when your own private key couldn't be read or decrypted, so nothing was sent, and 'prompt' when the server's keyboard-interactive challenge asks for more than the password (pass keyboardInteractive to answer it). If the connection drops or the framing breaks once the session is up, the session closes: pending calls reject with a SessionClosedError whose cause is the original error (such as a TransportError or FramingError), and the session's 'closed' event reports the same cause. An RPC timeout or an RpcError leaves the session open.
Programming errors
A mistake in the calling code isn't a NetconfError, so a handler that catches NetconfError never hides one:
- An argument of the wrong type or shape, or options that exclude each other, throw a
TypeError. So does misusing the API, such as attaching a second receiver to a connection. - A value out of range, such as a negative timeout, throws a
RangeError. - An error your own code throws (a transaction callback, a keyboard-interactive handler, a function that supplies a secret) reaches you unchanged, or as the
causeof the error that reports it, such as aTransactionError.
modules() is a lookup, not a programming error: a datastore or schema the server doesn't list rejects with a SchemaUnavailableError naming it.