Error Reporting

All errors are reported using the standard <rpc-error> element.

If the operation does not return any data, then the <rpc-reply> element will either contain 1 <ok/> element, or 1 or more <rpc-error> elements.

If the operation returns any data (i.e., the YANG rpc definition for the operation has an 'output' section), then the <rpc-reply> element may have both <rpc-error> and data elements within it. If there were errors in the input, then only 1 or more <rpc-error> elements will be returned. It is possible that the required data will be returned, after any errors, but not likely.

The internal netconfd-pro error code for each <rpc-error> is returned in an <error-info> extension called <error-number>.

Normally, the same <error-app-tag> and <error-message> values are returned for a specific error number. However, some YANG errors allow these fields to be user-defined. If there is a user-defined <error-app-tag> and/or <error-message> values, then they will be used instead of the default values.

This section describes the netconfd-pro implementation details which may affect <rpc-error> processing by a client application.

Error Reporting CLI Parameters

There are several CLI parameters that control the way errors will processed in the server, and reported to the client.

<error-severity> Element

The <error-severity> field will usually be set to 'error'. There are no warnings generated by netconfd-pro. However, the --with-warnings parameter can enable the non-standard use of the 'warning' value for this field.

<error-tag> Element

All NETCONF <error-tag> enumerations are supported, except 'partial-operation'. This error is being deprecated in the standard because nobody has implemented it.

If this field is set to 'invalid-value', then the <bad-value> element should be present in the <error-info>, identifying the invalid value that caused the problem.

All standard <error-info> contents are supported. The following table summarizes the different <error-tag> values. The <error-number> parameter is not shown in the 'error-info' column because it is added for every error-tag.

<error-tag> Summary

error-tag

error-info

description

access-denied

none

NACM denied access

bad-attribute

<bad-attribute> <bad-element> <bad-value>

just for the few attributes used in NETCONF

bad-element

<bad-element> <bad-value>

sometimes used instead of invalid-value

data-exists

none

nc:operation='create'

data-missing

none

nc:operation='delete' or 'replace'

in-use

none

edit on locked database

invalid-value

<bad-value>

for typedef constraints

lock-denied

<session-id>

for <lock> only

missing-attribute

<bad-attribute>

just for the few attributes used in NETCONF

missing-element

<bad-element>

mandatory parameters

o peration-not-supported

none

unsupported, false if-feature inside rpc

operation-failed

none

when no other error-tag applies

partial-operation

<ok-element> <err-element> <noop-element>

not implemented

resource-denied

none

malloc failed

rollback-failed

none

rollback-on-error failed

too-big

none

input too big to buffer

unknown-attribute

<bad-attribute> <bad-element>

for any non-NETCONF attributes found

unknown-element

<bad-element>

wrong element name in a known namespace

unknown-namespace

<bad-element>

module not loaded

malformed-message

None

base:1.1 framing lost in transport layer

<error-app-tag> Element

The <error-app-tag> field provided a more specific error classification than the <error-tag> field. It is included in every <rpc-error> response.

This field is encoded as a simple string.

It is possible that error-app-tag values from different vendors will use the same string. A client application needs to account for this shared namespace.

If the YANG 'error-app-tag' statement is defined for the specific error that occurred, then it will be used instead of the default value.

The following table describes the default <error-app-tag> values used by netconfd-pro:

<error-app-tag> Summary

error-app-tag

description

data-incomplete

the input parameters are incomplete

data-invalid

one or more input parameters are invalid

data-not-unique

unique statement violation (YANG, sec. 13.1)

duplicate-error

trying to create a duplicate list or leaf-list entry

general-error

no other description fits

instance-required

missing mandatory node (YANG, sec. 13.5)

internal-error

internal software error

io-error

NETCONF session IO error

libxml2-error

libxml2 internal error or parsing error

limit-reached

some sort of defined limit was reached

malloc-error

malloc function call failed

missing-choice

mandatory choice not found (YANG, sec. 13.6)

missing-instance

mandatory leaf not found (YANG, sec. 13.7)

must-violation

must expression is false (YANG, sec. 13.4)

no-access

access control violation

no-matches

<get-schema> module or revision search failed

no-support

operation or sub-operation not implemented

not-in-range

YANG range test failed

not-in-value-set

YANG enumeration or bits name is invalid

pattern-test-failed

YANG pattern test failed

recover-failed

commit or rollback-on-error failed to leave the target database unchanged

resource-in-use

in-use error or <create-subscription> while a subscription is already active

ssh-error

SSH transport error

too-few-elements

min-elements violation (YANG, sec. 13.3)

too-many-elements

max-elements violation (YANG, sec. 13.2)

<error-path> Element

The <error-path> field indicates the node that caused the error.

It is encoded as a YANG instance-identifier.

If the node that caused the error is within the incoming <rpc> request, then the error path will start with the <rpc> element, and contain all the node identifiers from this document root to the node that caused the error.

<error-path>/nc:rpc/nc:edit-config/nc:config/nacm:nacm/nacm:groups/nacm:group</error-path>

The 'xmlns' attributes which define the 'nc' and 'nacm' prefixes would be present in the <rpc-reply> or the <rpc-error> element start tags.

If the node that caused the error is not within the incoming <rpc> request, then the error path will start with the top-level YANG module element that contains the error, not the <rpc> element.

This extended usage of the <error-path> field is defined in the YANG specification, not the NETCONF specification. This situation will occur if <validate> or <commit> operations detect errors. It can also occur if the <test-option> for the <edit-config> operation is 'test-then-set', and errors unrelated to the provided in-line <config> content are reported. and contain all the node identifiers from this document root to the node that caused the error.

<error-path>/nacm:nacm/nacm:groups/nacm:group[name='admin']/groupIdentity</error-path>

<error-message> Element

The <error-message> field provides a short English language description of the error that usually corresponds to the <error-number> field.

If the YANG <error-message> statement is available for the error that occurred, it will be used instead of the default error message.

<error-info> Element

The <error-info> container is used to add error-specific data to the error report.

There are some standard elements that are returned for specific errors, and some elements specific to the netconfd-pro server.

<error-info> Summary

child node

description

<bad-attribute>

name of the XML attribute that caused the error

<bad-element>

name of the element that caused the error or contains the attribute that caused the error

<bad-value>

value that caused the error

<error-number>

internal error number for the error condition

<missing-choice>

name of the missing mandatory YANG choice

<session-id>

session number of the current lock holder

The "error-number" leaf can be controlled using the --with-error-number CLI parameter (added in 22.10-8). To remove this leaf, set this CLI parameter to 'false'.

Dynamic Error Messages

Dynamic error messages can include content from the configuration data, such as an interface name, or other administrative details.

A set of YANG extensions are used to configure the dynamic error strings. They are defined in yumaworks-extensions.yang.

The “errmsg” extension is used to specify a single dynamic error message. Zero or more of these statements can appear within a data node. The “errmsg” statement can appear within a “must” statement as well. It will resolve to the data node containing the “must” statement.

Multiple 'errmsg' statements can be defined for a single data node. Filters can be defined based on the 'error-tag' and 'error-app-tag' fields in the error being generated. An 'errmsg' can be defined for each 'error-message' language supported by the server.

errmsg Limitations

The “errmsg” statement is only applied under certain conditions:

  • There is an 'error-path' field reported in the RPC error message.

  • The 'error-path' object is a data node.

  • The 'error-path' object has an 'errmsg' that matches the error being generated.

  • There is an instance of the data node in the 'candidate' or 'running' datastores. For data that is being created, the errmsg may not be available. The data in the request message may be invalid or incomplete, so it is only safe to do XPath evaluation on a datastore.

errmsg Statements

The “errmsg” statement has a simple structure:

ywx:errmsg {
    [ywx:errmsg-parm]*
    [ywx:errmsg-tag]?
    [ywx:errmsg-apptag]?
    [ywx:errmsg-lang]?
}

The “errmsg” statement has 4 sub-statements:

  • errmsg-parm: specifies a parameter to use within the errmsg

  • errmsg-tag: specifies an “error-tag” filter for this errmsg

  • errmsg-apptag: specifies an “error-app-tag” filter for this errmsg

  • errmsg-lang: specifies a language filter for the errmsg. The --errmsg-lang CLI parameter value will be used to select an errmsg if this sub-statement is present

extension errmsg {
  description
    "Used within a data node statement to define
     a custom error-message filed within an 'rpc-error'
     or 'error' structure for some or all error conditions.

     The string format is restricted to plain text with
     the exception of the 2 character sequence '%s'.
     This special sequence will be replaced in the
     dynamic error message generation if an errmsg-parm
     statement is found to match the escape sequence.

     If this extension statement has no sub-statements,
     then it matches all errors for the object.
     If 'errmsg-tag' sub-statements are found, then
     this entry will match only those error-tag values.
     If 'errmsg-apptag' sub-statements are found, then
     this entry will match only those error-app-tag values.

     The 'basestr' argument must be formatted string.
     If any parameters are specified, then the corresponding
     'errmsg-parm' extension statements must be encoded within
     this errmsg statement.

     Multiple errmsg statements can be present in the same
     data node statement. They will be processed in order
     and the first matching statement will be used to
     generate the error-message value.

     Example:

        leaf my-network-id {
          type int32;
          ywx:errmsg 'Not a valid network ID for interface %s' {
            ywx:errmsg-parm '../../if:name';
            ywx:errmsg-apptag 'network-error';
          }
        }
    ";
  argument basestr;
}

extension errmsg-parm {
  description
    "Used within an errmsg statement to define
     a parameter for expansion within the errmsg basestr.
     There should be the correct number of expected parameters
     for the corresponding 'basestr' format string.

     The 'parmstr' argument must be an XPath path expression.
     The context node will be the data node containing the
     errmsg statement.
    ";
   argument parmstr;
 }

extension errmsg-tag {
  description
    "Used within an errmsg statement to define an
     error-tag value that will filter this errmsg.
     Multiple errmsg-tag and/or errmsg-apptag values
     form a conceptual OR expression.

     The 'tagstr' argument must be the error-tag value
     that will be matched.
    ";
  argument tagstr;
}

extension errmsg-apptag {
  description
    "Used within an errmsg statement to define an
     error-app-tag value that will filter this errmsg.
     Multiple errmsg-tag and/or errmsg-apptag values
     form a conceptual OR expression.

     The 'apptagstr' argument must be the error-app-tag
     value that will be matched.
    ";
  argument apptagstr;
}

extension errmsg-lang {
  description
    "Used within an errmsg statement to define the
     language code value that will filter this errmsg.
     Only one errmsg-lang statement may appear within
     an errmsg statement. The 'langstr' value will
     be compared to the 'errmsg-lang' CLI variable setting.
     If the strings are the same, the entry is used.

     If this statement is not present, then the errmsg entry
     will be used regardless of the 'errmsg-lang' CLI variable
     setting.

     The 'langstr' argument must be the language code
     value that will be matched.
    ";
  argument langstr;
}

The test-errmsg.yang module contains examples of the errmsg statement:

module test-errmsg {
  namespace "http://yumaworks.com/ns/test-errmsg";
  prefix "tm";
  import yumaworks-extensions { prefix ywx; }
  revision 2018-03-05;

  container top {
    list list1 {
      key a;
      leaf a { type string; }
      leaf b { type int32; }
      leaf test1 {
        ywx:errmsg "The value '%s' is invalid for the %s list entry" {
          ywx:errmsg-parm ".";
          ywx:errmsg-parm "../a";
          ywx:errmsg-tag "invalid-value";
        }
        type int8;
      }

      leaf test2 {
        must "../test1 != 8" {
          ywx:errmsg "The test1 value '%s' is not allowed if test2 is '%s'" {
             ywx:errmsg-parm "../test1";
             ywx:errmsg-parm ".";
             ywx:errmsg-apptag "must-violation";
          }
        }
        type uint32;

        ywx:errmsg "The b value is %s and the key is %s "
        + "for the invalid-value %s" {
          ywx:errmsg-tag "invalid-value";
          ywx:errmsg-parm "../b";
          ywx:errmsg-parm "../a";
          ywx:errmsg-parm ".";
        }
      }

      leaf test3 {
        type string;
        ywx:errmsg "This is %s the %s operation-failed %s msg" {
          ywx:errmsg-parm "../b";
          ywx:errmsg-parm "../test1";
          ywx:errmsg-parm ".";
          ywx:errmsg-lang "en";
        }

        ywx:errmsg "C'est %s l'opération %s a échoué %s msg" {
          ywx:errmsg-parm "../b";
          ywx:errmsg-parm "../test1";
          ywx:errmsg-parm ".";
          ywx:errmsg-lang "fr";
        }
      }
    }
  }

}

Using Annotations to Define Dynamic Error Messages

It is often undesirable to define YANG annotations like the ‘errmsg’ statement in YANG modules that are visible to customers. The --annotation CLI parameter can be used to specify a YANG module that contains annotations for another YANG module. The annotation YANG module is not advertised to clients. It is only used internally to “patch” the target YANG module with annotations and deviations.

The following example shows how a dynamic error message could be specified for the “type” leaf in the ietf-interfaces module. The annotation YANG module is called “errmsg-if.yang”. The server could be invoked with these configuration file parameters:

netconfd-pro {
  module ietf-interfaces
  module iana-if-type
  annotation errmsg-if
}

The errmsg-if.yang module is loaded at boot-time and the errmsg statements are applied to the /interfaces/interface/ltype leaf node.

module errmsg-if {

  namespace "http://netconfcentral.org/ns/errmsg-if";
  prefix "em";

  import yumaworks-extensions { prefix ywx; }
  import ietf-interfaces { prefix if; }

  revision 2018-04-12 {
      description "Initial revision.";
  }

  deviation /if:interfaces/if:interface/if:type {
    deviate add {
        ywx:errmsg "This is the name %s and type %s of the interface" {
          ywx:errmsg-parm "../name";
          ywx:errmsg-parm ".";
          ywx:errmsg-lang "en";
        }

    }
  }
}

Replacing a Standard Error Message

The --errmsg CLI parameter can be used to replace the standard error message for a specific error number.

  • The error numbers are listed with the error enumerations in the file ncx/status_enum.h.

  • For example, the error code 313 is assigned to the enumeration ERR_NCX_INVALID_PATTERN.

  • The default error message is “invalid pattern”.

  • The errmsg parameter is a string with 3 fields:

    <errnum>:<lang>:<msg>

    • <errnum> is the error number

    • <lang> is the language code (must be “en” for English to replace the default error string)

    • <msg> is the desired error message

To replace this default error message with the string

This is an invalid pattern specification

use the errmsg parameter as follows:

errmsg “313:en:”This is an invalid pattern specification”

Multi-Language Error Messages

The server can be configured to use error-message strings in a language other than English.

  • The --errmsg parameter is a leaf-list that allows a static error message to be configured at boot-time.

  • Each errmsg string contains an error number, language code, and error message.

  • See the --errmsg CLI parameter for details.

  • This parameter must be used together with the --errmsg-lang parameter to select an error message language other than English.

  • The Google Translate service is used to create the pre-configured language-specific errmsg configuration files (found in /usr/share/yumapro/util/errmsg-lang).

  • The language codes used in this program correspond to the ISO-639-1 codes defined by Google Translate languages

These files can be edited if desired and the strings replaced with custom values.

There is a set of translated error messages installed in the /usr/share/yumapro/util/errmsg-lang directory.

File

Language

errmsg-cs.conf

Czech

errmsg-da.conf

Danish

errmsg-de.conf

German

errmsg-en.conf

English

errmsg-es.conf

Spanish

errmsg-fr.conf

French

errmsg-he.conf

Hebrew

errmsg-hu.conf

Hungarian

errmsg-it.conf

Italian

errmsg-ja.conf

Japanese

errmsg-ko.conf

Korean

errmsg-nl.conf

Dutch

errmsg-no.conf

Norwegian

errmsg-pl.conf

Polish

errmsg-ru.conf

Russian

errmsg-sr.conf

Serbian

errmsg-zh-CN.conf

Chinese

Any configuration file can be used to configure errmsg parameters. The default translation files can be edited to change the error message for specific error numbers.

To use a translated error file, it must be placed in the configuration sub-directory. The default is the /etc/yumapro/netconfd-pro.d directory. To use a non-default location, set the --confdir CLI parameter.

The --errmsg-lang parameter must also be used, and set to the correct language code.

Example: Set up French error messages:

> sudo mkdir -p /etc/yumapro/netconfd-pro.d
> sudo cp /usr/share/yumapro/util/errmsg-lang/errmsg-fr.conf /etc/yumapro/netconfd-pro.d/

Add to the configuration file /etc/yumapro/netconfd-pro.conf:

netconfd-pro {
  errmsg-lang fr
}

instance-required Error Example

The instance-required error-app-tag is generated when a YANG leaf is mandatory, but was not set. An error will be returned right away if the target is the <running> configuration, or if the (default) 'test-then-set' option is used for the <test-option>. Otherwise, this error is generated when the <commit> operation is invoked.

data

description

error-tag

data-missing

error-app-tag

instance-required

error-path

identifies the leaf that is missing

error-info

none

error-number

310

Example Request:

  • create /test2 (?s used to skip the mandatory <a2> leaf, but the <foo> leaf is set)

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
  <nc:edit-config>
    <nc:target>
      <nc:candidate/>
    </nc:target>
    <nc:default-operation>none</nc:default-operation>
    <nc:config>
      <t:test2 nc:operation="create" xmlns:t="http://netconfcentral.org/ns/test">
        <t:foo>xxx</t:foo>
      </t:test2>
    </nc:config>
  </nc:edit-config>
</nc:rpc>

Example Error Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
  message-id="2" xmlns:t="http://netconfcentral.org/ns/test"
  xmlns:ncx="http://netconfcentral.org/ncx">
  <nc:rpc-error>
    <nc:error-type>application</nc:error-type>
    <nc:error-tag>data-missing</nc:error-tag>
    <nc:error-severity>error</nc:error-severity>
    <nc:error-app-tag>instance-required</nc:error-app-tag>
    <nc:error-path>/t:test2/t:a2</nc:error-path>
    <nc:error-message xml:lang="en">required value instance not found</nc:error-message>
    <nc:error-info>
      <ncx:error-number>310</ncx:error-number>
    </nc:error-info>
  </nc:rpc-error>
</nc:rpc-reply>

missing-choice Error Example

The missing-choice error is generated when a YANG choice is mandatory, but no case from the choice was set. An error will be returned right away if the target is the <running> configuration, or if the (default) 'test-then-set' option is used for the <test-option>. Otherwise, this error is generated when the <commit> operation is invoked.

data

description

error-tag

data-missing

error-app-tag

missing-choice

error-path

identifies the parent of the missing choice

error-info

<missing-choice>

error-number

296

Example Request:

  • create --target=/musttest (?s skip the mandatory choice)

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
  <nc:edit-config>
    <nc:target>
      <nc:candidate/>
    </nc:target>
    <nc:default-operation>none</nc:default-operation>
    <nc:config>
      <t:musttest nc:operation="create" xmlns:t="http://netconfcentral.org/ns/test"/>
    </nc:config>
  </nc:edit-config>
</nc:rpc>

Example Error Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2"
   xmlns:t="http://netconfcentral.org/ns/test" xmlns:ncx="http://netconfcentral.org/ncx">
   <nc:rpc-error xmlns:y="urn:ietf:params:xml:ns:yang:1">
     <nc:error-type>application</nc:error-type>
     <nc:error-tag>data-missing</nc:error-tag>
     <nc:error-severity>error</nc:error-severity>
     <nc:error-app-tag>missing-choice</nc:error-app-tag>
     <nc:error-path>/t:musttest</nc:error-path>
     <nc:error-message xml:lang="en">missing mandatory choice</nc:error-message>
     <nc:error-info>
       <y:missing-choice xmlns:y="urn:ietf:params:xml:ns:yang:1">musttest</y:missing-choice>
       <ncx:error-number>296</ncx:error-number>
     </nc:error-info>
   </nc:rpc-error>
 </nc:rpc-reply>

no-matches Error Example

The no-matches error is generated when parameters for the <get-schema> operation identify a non-existent YANG file.

data

description

error-tag

operation-failed

error-app-tag

no-matches

error-path

identifies the <identifier> or <revision> parameter in the <get-schema> request

error-info

<bad-value>

error-number

365

Example Request:

  • get-schema identifier=foo version= format=yang

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="3">
  <ns:get-schema xmlns:ns="urn:ietf:params:xml:ns:netconf:state">
    <ns:identifier>foo</ns:identifier>
    <ns:version/>
    <ns:format>ns:yang</ns:format>
  </ns:get-schema>
</nc:rpc>

Example Error Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="3"
  xmlns:ns="urn:ietf:params:xml:ns:netconf:state" xmlns:ncx="http://netconfcentral.org/ncx">
  <nc:rpc-error>
    <nc:error-type>protocol</nc:error-type>
    <nc:error-tag>operation-failed</nc:error-tag>
    <nc:error-severity>error</nc:error-severity>
    <nc:error-app-tag>no-matches</nc:error-app-tag>
    <nc:error-path>/nc:rpc/ns:get-schema/ns:input/ns:identifier</nc:error-path>
    <nc:error-message xml:lang="en">no matches found</nc:error-message>
    <nc:error-info>
      <ncx:bad-value>foo</ncx:bad-value>
      <ncx:error-number>365</ncx:error-number>
    </nc:error-info>
  </nc:rpc-error>
</nc:rpc-reply>

not-in-range Error Example

The not-in-range error is generated when a numeric type violates a YANG range statement.

data

description

error-tag

invalid-value

error-app-tag

not-in-range

error-path

identifies the leaf or leaf-list node that is not in range

error-info

<bad-value>

error-number

288

Example Request:

  • create /int8.1 value=1000

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="4" trace-id="4" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <edit-config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <target>
      <candidate/>
    </target>
    <default-operation>merge</default-operation>
    <test-option>set</test-option>
    <config>
      <int8.1 xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
        nc:operation="merge"
        xmlns="http://netconfcentral.org/ns/test">1000</int8.1>
    </config>
  </edit-config>
</rpc>

Example Error Reply:

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="4" trace-id="4" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
  xmlns:t="http://netconfcentral.org/ns/test"
  xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
  xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <rpc-error>
    <error-type>protocol</error-type>
    <error-tag>invalid-value</error-tag>
    <error-severity>error</error-severity>
    <error-app-tag>not-in-range</error-app-tag>
    <error-path>/nc:rpc/nc:edit-config/nc:config/t:int8.1</error-path>
    <error-message xml:lang="en">value not in range</error-message>
    <error-info>
      <bad-value xmlns="http://netconfcentral.org/ns/yuma-ncx">1000</bad-value>
      <error-number xmlns="http://netconfcentral.org/ns/yuma-ncx">288</error-number>
    </error-info>
  </rpc-error>
</rpc-reply>