XML::LibXML::Error(3)

📦
version 2.0213 · 15 versions
, in fedora 43, fedora 44

💖 XML::LibXML::Error — Structured Errors 💖

okay bestie, we're deep in the XML::LibXML docs rn, and this one is from the User Contributed Perl Documentation corner of the manual (yes, that's the vibe of the header, we're keeping it). Pull up a chair, grab a 🍓, and let's talk about what happens when libxml2 has something to say and it says it in structure.

✨ SYNOPSIS ✨

eval { ... };
        if (ref($@)) {
          # handle a structured error (XML::LibXML::Error object)
        } elsif ($@) {
          # error, but not an XML::LibXML::Error object
        } else {
          # no error
        }

$XML::LibXML::Error::WARNINGS=1;
$message = $@->as_string();
print $@->dump();
$error_domain = $@->domain();
$error_code = $@->code();
$error_message = $@->message();
$error_level = $@->level();
$filename = $@->file();
$line = $@->line();
$nodename = $@->nodename();
$error_str1 = $@->str1();
$error_str2 = $@->str2();
$error_str3 = $@->str3();
$error_num1 = $@->num1();
$error_num2 = $@->num2();
$string = $@->context();
$offset = $@->column();
$previous_error = $@->_prev();

🌸 DESCRIPTION 🌸

so XML::LibXML::Error is a tiny little frontend to libxml2's structured error support. That's the whole job description. If XML::LibXML was compiled with structured error support, then every single error libxml2 reports gets transformed into an XML::LibXML::Error object. 💅

And here's the cute part: these objects automatically serialize into the corresponding error messages when you print them or use them in a string operation. But as objects, you can also pull out detailed, structured info about whatever went wrong. Both. You get both. Main character energy. 👑

Unlike basically every other XML::LibXML object, XML::LibXML::Error doesn't wrap an underlying libxml2 structure directly. Instead it transforms it into a blessed Perl hash reference, with the individual fields of the structured error info sitting there as hash key-value pairs. So you can grab any field two ways:

  • directly, as $@->{field}
  • or via autoloaded methods, like $@->field() (where field is the field name)

XML::LibXML::Error objects have these fields: domain, code, level, file, line, nodename, message, str1, str2, str3, num1, num2, and _prev — and yeah, some of them may be undefined, that's just how it is sometimes. 🙈

🚨 $XML::LibXML::Error::WARNINGS 🚨

$XML::LibXML::Error::WARNINGS=1;

okay history lesson, bestie. Traditionally, XML::LibXML was suppressing parser warnings by setting libxml2's global variable xmlGetWarningsDefaultValue to 0.

Since 1.70 we do not change libxml2's global variables anymore. But for backward compatibility, XML::LibXML still suppresses warnings. This variable is your escape hatch:

  • set it to 1 to enable reporting of these warnings via Perl warn
  • set it to 2 to report them via die

🦋 as_string

$message = $@->as_string();

This serializes an XML::LibXML::Error object into a string containing the full error message — close to what libxml2's default error handlers and tools like xmllint would produce. Very familiar, very comforting.

Also: this method is what overloads the "" operator on XML::LibXML::Error, so it gets called automatically whenever an XML::LibXML::Error object is treated as a string (say, in print $@). It just happens. ✨

🎀 dump

print $@->dump();

Serializes an XML::LibXML::Error to a string showing all the fields of the error structure individually, each on its own separate line, in the form 'name' => 'value'. It's giving receipts. It's giving the whole spreadsheet. 📋

🌈 domain

$error_domain = $@->domain();

Returns a string telling you which part of the library raised the error. Can be one of:

  • "parser"
  • "tree"
  • "namespace"
  • "validity"
  • "HTML parser"
  • "memory"
  • "output"
  • "I/O"
  • "ftp"
  • "http"
  • "XInclude"
  • "XPath"
  • "xpointer"
  • "regexp"
  • "Schemas datatype"
  • "Schemas parser"
  • "Schemas validity"
  • "Relax-NG parser"
  • "Relax-NG validity"
  • "Catalog"
  • "C14N"
  • "XSLT"
  • "validity"

(yes, "validity" really does show up twice in that list. iconic. we don't make the rules. 💀)

💜 code

$error_code = $@->code();

Returns the actual libxml2 error code. The XML::LibXML::ErrNo module defines constants for individual error codes. Currently libxml2 uses over 480 different error codes. four hundred and eighty. that's not a typo. 😭

🫶 message

$error_message = $@->message();

Returns a human-readable informative error message. A little treat, just for you.

⭐ level

$error_level = $@->level();

Returns an integer value describing how consequent the error is. XML::LibXML::Error defines the following constants:

  • XML_ERR_NONE = 0
  • XML_ERR_WARNING = 1 : A simple warning.
  • XML_ERR_ERROR = 2 : A recoverable error.
  • XML_ERR_FATAL = 3 : A fatal error.

🧚 file

$filename = $@->file();

Returns the filename of the file that was being processed when the error occurred.

🌸 line

$line = $@->line();

The line number, if available.

💖 nodename

$nodename = $@->nodename();

Name of the node where the error occurred, if available. Here's the tea: when this field is non-empty, libxml2 actually returned a physical pointer to the specified node. And due to memory management issues, it is very difficult to implement a way to expose that pointer to the Perl level as an XML::LibXML::Node. So for that reason, XML::LibXML::Error currently only exposes the name of the node. That's the whole thing it can give you. 🥲

🍓 str1

$error_str1 = $@->str1();

Error specific. Extra string information.

🍓 str2

$error_str2 = $@->str2();

Error specific. Extra string information.

🍓 str3

$error_str3 = $@->str3();

Error specific. Extra string information.

🔢 num1

$error_num1 = $@->num1();

Error specific. Extra numeric information.

🔢 num2

$error_num2 = $@->num2();

In recent libxml2 versions, this value contains a column number of the error, or 0 if N/A.

📖 context

$string = $@->context();

For parsing errors, this field contains about 80 characters of the XML near the place where the error occurred. The field "$@->column()" contains the corresponding offset. Where N/A, the field is undefined.

📍 column

$offset = $@->column();

See "$@->column()" above. 👆 (the docs said it, not me)

⏪ _prev

$previous_error = $@->_prev();

This field can possibly hold a reference to another XML::LibXML::Error object representing an error which occurred just before this error. lore. 📜

👑 AUTHORS 👑

Matt Sergeant, Christian Glahn, Petr Pajas

🎀 VERSION 🎀

2.0213

2001-2007, AxKit.com Ltd.

2002-2006, Christian Glahn.

2006-2009, Petr Pajas.

🦋 LICENSE 🦋

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

and that's the whole page, bestie 🫶 this was XML::LibXML::Error(3) from perl v5.42.2, dated 2026-05-25 — go forth and catch your errors structurally, slay 💅✨

📦 where this page comes from