Cisco IOS XR XML API Guide, Cisco IOS XR Release 4.1
Error Reporting in Cisco XML Responses
Downloads: This chapterpdf (PDF - 372.0KB) The complete bookPDF (PDF - 7.34MB) | Feedback

Error Reporting in Cisco XML Responses

Table Of Contents

Error Reporting in Cisco XML Responses

Types of Reported Errors

Error Attributes

Transport Errors

XML Parse Errors

XML Schema Errors

Operation Processing Errors

Error Codes and Messages


Error Reporting in Cisco XML Responses


The XML responses returned by the router contains error information as appropriate, including the operation, object, and cause of the error when possible. The error codes and messages returned from the router may originate in the XML agent or in one of the other infrastructure layers; for example, the XML Service Library, XML Parser Library, or Configuration Manager.

Types of Reported Errors

The types of potential errors in XML Responses are listed in Table 11-1.

Table 11-1 Reported Error Types 

Error Type
Description

Transport errors

Transport-specific errors are detected within the XML agent (and include failed authentication attempts).

XML parse errors

XML format or syntax errors are detected by the XML Parser Library (and include errors resulting from malformed XML, mismatched XML tags, and so on).

XML schema errors

XML schema errors are detected by the XML operation provider within the infrastructure (and include errors resulting from invalid operation types, invalid object hierarchies, values out of range, and so on).

Operation processing errors

Operation processing errors are errors encountered during the processing of an operation, typically as a result of committing the target configuration (and include errors returned from Configuration Manager and the infrastructure such as failed authorization attempts, and "invalid configuration errors" returned from the back-end Cisco IOS XR applications).


These error categories are described in the following sections:

Error Attributes

Transport Errors

XML Parse Errors

XML Schema Errors

Operation Processing Errors

Error Codes and Messages

Error Attributes

If one or more errors occur during the processing of a requested operation, the corresponding XML response includes error information for each element or object class in error. The error information is included in the form of ErrorCode and ErrorMsg attributes providing a relevant error code and error message respectively.

If one or more errors occur during the processing of an operation, error information is included for each error at the appropriate point in the response. In addition, error attributes are added at the operation element level. As a result, the client application does not have to search through the entire response to determine if an error has occurred. However, the client can still search through the response to identify each of the specific error conditions.

Transport Errors

Transport-specific errors, including failed authentication attempts, are handled by the appropriate XML agent.

XML Parse Errors

This general category of errors includes those resulting from malformed XML and mismatched XML tags.

The router checks each XML request, but does not validate the request against an XML schema. If the XML contains invalid syntax and thus fails the well-formedness check, the error indication is returned in the form of error attributes placed at the appropriate point in the response. In such cases, the response may not contain the same XML as was received in the request, but just the portions to the point where the syntax error was encountered.

In the following example, the client application sends a request to the router that contains mismatched tags, that is, the opening <BGPEntity> tag is not paired with a closing </BGPEntity> tag. This example illustrates the format and placement of the error attributes.


Note The actual error codes and messages might be different than what is shown in this example. Also, the actual error attributes does not contain new line characters.


Sample XML Client Request Containing Mismatched Tags

<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
  <Get>
    <Configuration>
      <BGP MajorVersion="24" MinorVersion="0">
        <AS>
          <Naming>
            <AS>0</AS>
          </Naming>
          <FourByteAS>
            <Naming><AS>3</AS></Naming>
            <DefaultVRF>
              <BGPEntity>
            </DefaultVRF>
          </FourByteAS>
        </AS>
      </BGP>
    </Configuration>
  </Set>
</Request>

Sample XML Response from the Router

<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0">
  <Get xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ErrorCode="0x43679000"
      ErrorMsg="&apos;XML Service Library&apos; detected the &apos;warning&apos;
      condition &apos;An error was encountered in the XML beneath this operation tag
      &apos;">
    <Configuration ErrorCode="0xa240da00" ErrorMsg="&apos;XML Infrastructure &apos;
        detected the &apos;fatal&apos; condition &apos;Opening and ending tag does not
        match&apos;"/>
  </Get>
  <ResultSummary ErrorCount="1"/>
</Response>

XML Schema Errors

XML schema errors are detected by the XML operation providers. This general category of errors includes those resulting from invalid operation types, invalid object hierarchies, and invalid naming or value elements. However, some schema errors may go undetected because, as previously noted, the router does not validate the request against an XML schema.

In the following example, the client application has requested a <Set> operation specifying an object <ExternalRoutes> that does not exist at this location in the Border Gateway Protocol (BGP) component hierarchy. This example illustrates the format and placement of the error attributes.


Note The actual error codes and messages may be different than those shown in the example.


Sample XML Client Request Specifying an Invalid Object Hierarchy

<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
  <Get>
    <Configuration>
      <BGP MajorVersion="24" MinorVersion="0">
        <AS>
          <Naming> 
            <AS>0</AS>
          </Naming>
          <FourByteAS>
            <Naming><AS>3</AS></Naming>
           <DefaultVRF>
             <Global>
               <ExternalRoutes>10</ExternalRoutes>
             </Global>
           </DefaultVRF>
          </FourByteAS>
        </AS>
      </BGP>
    </Configuration>
  </Set>
</Request>

Sample XML Response from the Router

<?xml version="1.0" encoding="UTF-8"?>  
<Response MajorVersion="1" MinorVersion="0">
  <Set xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ErrorCode="0x4368a400"
       ErrorMsg="&apos;XML Service Library&apos; detected the &apos;warning&apos;
       condition &apos;An error was encountered in the XML beneath this operation
       tag&apos;">
    <Configuration>
      <BGP MajorVersion="24" MinorVersion="0"
        <AS>
          <Naming>
            <AS>0</AS>
          </Naming>
           <FourByteAS>
             <Naming><AS>3</AS></Naming>
            <DefaultVRF>
              <Global ErrorCode="0x4368a400" ErrorMsg="&apos;XMLMDA&apos; detected the 
              &apos;warning&apos; condition &apos;
              The XML request does not conform to the schema. A child element of
              the element on which this error appears is invalid. No such child
              element name exists at this location in the schema. Please check
              the request against the schema.&apos;"/>
            </DefaultVRF>
        </AS>
      </BGP>
    </Configuration>
  </Set>
  <ResultSummary ErrorCount="0"/>
</Response> 

The following example also illustrates a schema error. In this case, the client application has requested a <Set> operation specifying a value for the <GracefulRestartTime> object that is not within the range of valid values for this item.

Sample XML Request Specifying an Invalid Object Value Range

<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
  <Set>
    <Configuration>
      <BGP MajorVersion="24" MinorVersion="0">
        <AS>
          <Naming> 
            <AS>0</AS>
          </Naming>
          <FourByteAS>
            <Naming><AS>3</AS></Naming>
            <DefaultVRF>
              <Global>
                <GracefulRestartTime>6000</GracefulRestartTime>
              </Global>
            </DefaultVRF>
          </FourByteAS>
        </AS>
      </BGP>
    </Configuration>
  </Set>
</Request>

Sample XML Response from the Router

<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0">
  <Set xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ErrorCode="0x4368a800"
       ErrorMsg="&apos;XML Service Library&apos; detected the &apos;warning&apos;
       condition &apos;An error was encountered in the XML beneath this operation
       tag&apos;">
    <Configuration>
      <BGP MajorVersion="24" MinorVersion="0">
        <AS>
          <Naming>
            <AS>0</AS>
          </Naming> 
           <FourByteAS>
             <Naming><AS>3</AS></Naming>
            <DefaultVRF>
              <Global>
                <GracefulRestartTime ErrorCode="0x4368a800" ErrorMsg=&apos;
                XMLMDA&apos; detected the &apos;warning&apos; condition &apos;
                The XML request does not conform to the schema. The character data
                contained in the element on which this error appears (or one of its
                child elements) does not conform to the XML schema for its datatype.
                Please check the request against the schema.&apos;"/>
               </Global>
            </DefaultVRF>
        </AS>
      </BGP>
    </Configuration>
  </Set>
  <ResultSummary ErrorCount="1"/>
</Response>

Operation Processing Errors

Operation processing errors include errors encountered during the processing of an operation, typically as a result of committing the target configuration after previous <Set> or <Delete> operations. While processing an operation, errors are returned from Configuration Manager and the infrastructure, failed authorization attempts occur, and "invalid configuration errors" are returned from the back-end
Cisco IOS XR applications.

The following example illustrates an operation processing error resulting from a <GetNext> request specifying an unrecognized iterator ID:

Sample XML Client Request and Processing Error

<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
  <GetNext IteratorID="1" Abort="true"/>
</Request>

Sample XML Response from the Router

<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0" ErrorCode="0xa367a800" ErrorMsg="&apos;
     XML Service Library&apos; detected the &apos;fatal&apos; condition &apos;The XML
     Infrastructure has been provided with an iterator ID which is not recognized. The
     iterator is either invalid or has timed out.&apos;"/>

Error Codes and Messages

The error codes and messages returned from the router may originate in any one of several components.

The error codes (cerrnos) returned from these layers are 32-bit integer values. In general, for a given error condition, the error message returned in the XML is the same as the error message displayed on the CLI.