Chapter 10 - Error Reporting in Cisco CRS-1 Series XML Responses

Table Of Contents

Error Reporting in Cisco CRS-1 Series 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 CRS-1 Series XML Responses

The extensible markup language (XML) responses returned by the Cisco CRS-1 Series Carrier Routing System (Cisco CRS-1 Series) 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 Cisco CRS-1 Series router may originate in the XML agent or in one of the other Cisco CRS-1 Series infrastructure layers; for example, the XML Service Library, XML Parser Library, or Configuration Manager.

Note The XML application programming interface (API) code is available for use on any Cisco platform that runs Cisco IOS XR software.

Types of Reported Errors

The types of potential errors in Cisco CRS-1 Series XML Responses are categorized in Table 10-1.

Table 10-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 Cisco CRS-1 Series 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 Cisco CRS-1 Series infrastructure such as failed authorization attempts, and "invalid configuration errors" returned from the back-end Cisco CRS-1 Series operating system 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 Cisco CRS-1 Series 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 Cisco CRS-1 Series 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="1" MinorVersion="0">
        <AS>
          <Naming>
            <AS>3</AS>
          </Naming>
          <BGPEntity>
        </AS>
      </BGP>
    </Configuration>
  </Set>
</Request>
Sample XML Response from the Cisco CRS-1 Series 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="'XML Service Library' detected the 'warning'
      condition 'An error was encountered in the XML beneath this operation tag
      '">
    <Configuration ErrorCode="0xa240da00" ErrorMsg="'XML Infrastructure '
        detected the 'fatal' condition 'Opening and ending tag does not
        match'"/>
  </Get>
</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 Cisco CRS-1 Series 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">
  <Set>
    <Configuration>
      <BGP MajorVersion="1" MinorVersion="0">
        <AS>
          <Naming>
            <AS>3</AS>
          </Naming>
          <Global>
            <ExternalRoutes>10</ExternalRoutes>
          </Global>
        </AS>
      </BGP>
    </Configuration>
  </Set>
</Request>
Sample XML Response from the Cisco CRS-1 Series Router

<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
  <Set xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ErrorCode="0x4368a400"
       ErrorMsg="'XML Service Library' detected the 'warning'
       condition 'An error was encountered in the XML beneath this operation
       tag'">
    <Configuration>
      <BGP MajorVersion="1" MinorVersion="0"
        <AS>
          <Naming>
            <AS>3</AS>
          </Naming>
          <Global ErrorCode="0x4368a400" ErrorMsg="'XMLMDA' detected the               'warning' condition '

              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.'"/>

        </AS>
      </BGP>
    </Configuration>
  </Set>
</Request>

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="1" MinorVersion="0">
        <AS>
          <Naming>
            <AS>3</AS>
          </Naming>
          <Global>
            <GracefulRestartTime>6000</GracefulRestartTime>
          </Global>
        </AS>
      </BGP>
    </Configuration>
  </Set>
</Request>
Sample XML Response from the Cisco CRS-1 Series Router

<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
  <Set xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ErrorCode="0x4368a800"
       ErrorMsg="'XML Service Library' detected the 'warning'
       condition 'An error was encountered in the XML beneath this operation
       tag'">
    <Configuration>
      <BGP MajorVersion="1" MinorVersion="0">
        <AS>
          <Naming>
            <AS>3</AS>
          </Naming>
          <Global>
            <GracefulRestartTime ErrorCode="0x4368a800" ErrorMsg='
                XMLMDA' detected the 'warning' condition '
                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.'"/>
          </Global>
        </AS>
      </BGP>
    </Configuration>
  </Set>
</Request>

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 Cisco CRS-1 Series infrastructure, failed authorization attempts, and "invalid configuration errors" returned from the back-end Cisco CRS-1 Series operating system 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 Cisco CRS-1 Series Router

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

For more information on errors resulting from a commit of the target configuration, see the "Commit Errors" section on page 2-33.

Error Codes and Messages

The error codes and messages returned from the Cisco CRS-1 Series 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 command line interface (CLI).

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 Cisco CRS-1 Series 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 Cisco CRS-1 Series infrastructure such as failed authorization attempts, and "invalid configuration errors" returned from the back-end Cisco CRS-1 Series operating system applications).