Troubleshooting XmlCatalog Errors: Common Issues and FixesXmlCatalog (often written as XmlCatalog or XML Catalog) is a mechanism to map public identifiers, system identifiers, and URIs to local resources so XML parsers and tools can resolve external entities, DTDs, schemas, and other resources without always accessing the network. While XML catalogs improve reliability and performance, misconfiguration or subtle differences between tools and implementations can cause errors that are sometimes hard to diagnose.
This article walks through the most common XmlCatalog problems, explains why they happen, and gives practical fixes, examples, and debugging tips that apply across popular tools (Apache Xerces, libxml2, Saxon, Ant’s xmlcatalog task, Java’s JAXP, Maven, Gradle, and system-specific catalog implementations).
Table of contents
- Basics: what an XML catalog does and common formats
- Typical error symptoms and their root causes
- Creating and validating a correct catalog file
- Tool-specific gotchas and fixes
- Debugging tips and diagnostic commands
- Best practices to avoid future issues
Basics: what an XML catalog does and common formats
An XML catalog maps identifiers that appear in XML documents (public IDs, system IDs, URIs) to local file locations. When an XML processor encounters an external reference (e.g., DOCTYPE, external entity, XInclude, or schemaLocation), it asks a resolver which can consult a catalog to return a local replacement URI.
Common catalog formats:
- OASIS XML Catalogs (RFC 4706-like implementations) — the most widely used XML catalog format; XML-based, supports
, , , , , and / . - legacy catalog files (Apache-style plain-text) — older tools sometimes support simpler formats.
- vendor-specific formats and APIs (e.g., Java CatalogResolver implementations)
Key mapping types:
- public: maps PUBLIC identifiers (formal public IDs)
- system: maps system identifiers (system IDs, often URLs)
- uri: maps URIs used directly (e.g., schemaLocation)
- rewriteSystem / rewriteURI: perform prefix rewriting for many related resources
- delegatePublic / delegateSystem: delegate lookups for namespaces or prefixes to another catalog
Typical error symptoms and their root causes
Below are common symptoms you may encounter, with likely underlying causes.
- “Resource not found” or unresolved external entity
- Cause: catalog missing an entry for the used system/public ID or the mapped local path is incorrect.
- Wrong resource loaded (outdated or unexpected)
- Cause: catalog entry points to an old file, or rewrite rules match unexpectedly broad prefixes.
- Catalog ignored entirely
- Cause: resolver not registered with the XML processor, wrong system property, or tool not supporting catalogs by default.
- Malformed catalog file errors
- Cause: invalid XML in the catalog, wrong namespace, or not matching the catalog DTD/schema.
- Circular delegation or infinite loop
- Cause: rewrite/delegate rules that refer back to each other or self-referential mappings.
- Canonicalization/signature failures (XML Signature, XML Canonicalization)
- Cause: different parser/resolver loads slightly different input (encodings, line endings), or catalog changes resource content.
- Relative path issues when running in CI or different working directories
- Cause: catalog entries use relative paths that are resolved relative to a different base than expected.
- Mixed catalog formats or incompatible entries
- Cause: combining OASIS XML catalog with legacy plain-text entries without proper translation or support.
Creating and validating a correct catalog file
- Use the OASIS XML Catalog format. Start with a minimal, well-formed catalog:
<?xml version="1.0" encoding="UTF-8"?> <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"> <public publicId="-//W3C//DTD XHTML 1.0 Strict//EN" uri="file:///usr/local/share/xml/dtds/xhtml1-strict.dtd"/> <system systemId="http://example.com/schemas/myschema.xsd" uri="file:///home/user/schemas/myschema.xsd"/> <uri name="http://example.com/resources/resource.xml" uri="file:///home/user/resources/resource.xml"/> </catalog> - Validate catalog syntax:
- Ensure root element uses correct namespace: urn:oasis:names:tc:entity:xmlns:xml:catalog
- Use an XML validator or xmllint to check well-formedness:
- xmllint –noout catalog.xml
- Confirm file URIs are correct:
- Use absolute file:// URIs when possible.
- If using relative paths, ensure the base for resolution is the process working directory or the catalog’s location per your resolver’s behavior.
- Prefer uri/system/public entries for explicit references; use rewriteSystem for mapping entire URL prefixes.
Tool-specific gotchas and fixes
Java (JAXP) and CatalogResolvers
- Symptom: JAXP-based parsers ignore your catalog.
- Fixes:
- Use a CatalogResolver implementation (e.g., from Apache XML Commons Resolver or Saxon).
- Register it with the factory:
- For SAXParserFactory: setProperty(”http://apache.org/xml/properties/entity-resolver”, resolver) or setEntityResolver on the parser.
- For TransformerFactory or SchemaFactory, use the provider’s documented property (Saxon: Configuration.setEntityResolver).
- Ensure resolver library is on the classpath and no conflicting resolver implementation overrides it.
- Example: in Maven builds, add xmlresolver or resolver dependency (Apache XML Resolver) and configure the code or system properties.
Ant’s xmlcatalog task
- Symptom: Ant resolves differently between local runs and CI.
- Fixes:
- Use absolute paths or ensure the catalogfile attribute points to the right location.
- Ant supports OASIS catalogs but needs correct catalog entries; use nested
entries or external catalog files. - Ensure Ant version supports the catalog features you rely on (rewrite/delegate support added in later versions).
libxml2 (xmllint) and XML_CATALOG_FILES
- Symptom: xmllint still fetches network resources.
- Fixes:
- Set the environment variable XML_CATALOG_FILES to the path(s) of catalog files:
- export XML_CATALOG_FILES=/path/to/catalog.xml
- Use –noout –catalogs options; ensure the binary was compiled with catalog support.
- Verify catalog entries use correct URIs (file:///…) and that the resolver supports public/system/uri entries.
- Set the environment variable XML_CATALOG_FILES to the path(s) of catalog files:
Saxon (XSLT/XQuery)
- Symptom: Saxon ignores catalog for schema resolution.
- Fixes:
- Saxon uses the catalog resolver if you configure it in the Configuration object or by supplying a CatalogResolver via the JAXP entity resolver properties.
- For Saxon EE/HE, ensure you pass a CatalogResolver or set system-wide resolver via system properties if needed.
Maven and Gradle builds
- Symptom: Builds fetch XSDs/DTDs from the web, failing in offline environments.
- Fixes:
- Add xml-resolver or resolve plugin and configure to use catalogs.
- Use the maven-dependency-plugin or resources plugin to ensure catalog and schema files are included in the build.
- For Gradle, configure the XML parsing tasks or add a resolver library to the buildscript classpath.
Debugging tips and diagnostic commands
- Turn on resolver or parser debugging/logging:
- Many resolver libraries have verbose flags or logging you can enable (e.g., set logger to DEBUG for Apache Resolver).
- Use xmllint with catalogs:
- xmllint –noout –catalogs –dtdvalid foo.dtd foo.xml
- Test catalog entries explicitly:
- Create a small XML that references the exact system/public ID and run the parser with the catalog to see if mapping occurs.
- Check effective URIs:
- Use an EntityResolver implementation that logs the requested systemId/publicId and returned URI.
- Inspect JAR/classpath conflicts:
- Print classpath used by the process; multiple resolver implementations can conflict.
- Validate file URI accessibility:
- Use curl or file listing to confirm local files exist and are readable by the process user.
- Reproduce with minimal example:
- Reduce to a tiny XML, a catalog with one mapping, and the same parser invocation; if this works, incrementally add complexity.
Examples of common fixes
- Catalog ignored because the parser uses default EntityResolver:
- Add/plug in Apache XML Resolver:
- Add dependency: xml-resolver or resolver.jar
- Register resolver with parser factory or transformer factory.
- Relative paths break in CI:
- Change catalog to use absolute file URIs or make CI set CWD appropriately:
- Replace “file:///home/ci/build/schemas/myschema.xsd” or use environment variable substitution in build scripts.
- Unexpected rewrite mapping:
- Narrow the rewrite prefix or add a more specific system/public entry before broad rewrite rules.
- Example: use rewriteSystem only for “http://example.com/schemas/v1/” instead of “http://example.com/”.
- Duplicate or conflicting entries:
- Consolidate catalogs or use delegate rules deliberately; ensure order of precedence is correct for your resolver implementation.
Best practices to avoid XmlCatalog errors
- Keep catalogs under version control with your project and include them in build artifacts.
- Use absolute file:// URIs where possible to avoid CWD-sensitive failures.
- Favor explicit mappings for critical resources; use rewrite/delegate sparingly and test thoroughly.
- Include a small test that verifies catalog resolution as part of CI (a unit test or build task that parses a sample XML).
- Document catalog location, expected base paths, and resolver configuration in project README or build docs.
- Standardize on one resolver implementation across tools (e.g., Apache XML Resolver) to reduce differences.
Quick checklist when something breaks
- Is the catalog file well-formed and using the OASIS catalog namespace?
- Does the catalog contain an entry for the exact public/system/URI used?
- Are the mapped URIs reachable and correct (file permissions, absolute vs. relative)?
- Is a catalog-aware resolver registered with the parser/tool?
- Are you running the same resolver implementation/version across environments?
- Can you reproduce the problem with a minimal test case?
Troubleshooting XmlCatalog errors often comes down to careful validation: verify the catalog, confirm the mappings, ensure the resolver is properly installed and configured, and use minimal reproducible examples to isolate the issue. Following the tool-specific fixes and best practices above will resolve the vast majority of catalog-related failures.
Leave a Reply