v5.7.x rejects valid XML numeric character references like 

[danibuiza]

Description

After upgrading from fast-xml-parser@5.5.8 to 5.7.1, the parser rejects valid XML numeric character references such as 
 (carriage return).

Error Message

Error: [EntityReplacer] Invalid character '#' in entity name: "#xD"

Reproduction

This occurs when parsing XML responses from AWS S3 (via @aws-sdk/xml-builder which uses fast-xml-parser). AWS S3 responses contain XML with standard numeric character references like 
.

Expected Behavior


 is a valid XML numeric character reference representing carriage return (U+000D). According to the XML specification, numeric character references in the form &#xNNNN; (hexadecimal) or &#NNNN; (decimal) should be accepted.

Reference: https://www.w3.org/TR/xml/#NT-CharRef

Root Cause Hypothesis

The issue appears to be related to the dependency change in v5.7.x from fast-xml-builder to @nodable/entities. The new entity handling seems to incorrectly treat #xD as an entity name rather than recognizing it as a numeric character reference.

Environment

• fast-xml-parser version: 5.7.1
• Node.js version: 24.x
• Downstream dependency: @aws-sdk/xml-builder (AWS SDK v3)

Workaround

Pinning to fast-xml-parser@5.5.8 resolves the issue.

[github-actions]

We're glad you find this project helpful. We'll try to address this issue ASAP. You can join Discord channel(https://discord.gg/X4Qp9u6Vz) for anonucements and pre release discussions. Don't forget to star this repo.

[Lucas-C]

I'm also facing this issue.

In my case, the error is raised by LambdaClient.send() from @aws-sdk/client-lambda.

Upgrading to fast-xml-parser@5.7.2 solved the problem.

[abhu85]

I investigated this and found two related issues:

v5.7.1 (original report): setExternalEntities() calls validateEntityName() which throws on #-prefixed entity names. This was partially fixed in v5.7.2 by passing external entities through the constructor instead (commit ebaedc0).

v5.7.2 (remaining issue): While the error is gone, addEntity('#xD', '\r') is silently ignored because the EntityDecoder's NCR path intercepts #-prefixed tokens before checking the named entity map. This means 
 stays as literal text instead of being replaced with the registered value.

Confirmed behavior across versions:

• v5.5.8: addEntity('#xD', '\r') works correctly
• v5.7.1: throws Invalid character '#' in entity name: "#xD"
• v5.7.2: no error, but addEntity('#xD', '\r') is silently ignored

Note: If you're using the AWS SDK (@aws-sdk/xml-builder), v5.7.2 works because the SDK provides its own entityDecoder with numericAllowed: true, bypassing this code path entirely. The issue affects direct users of addEntity with #-prefixed keys.

Submitted a fix in #826 that separates #-prefixed external entities and resolves them via pre-processing before the EntityDecoder's decode pass. All 316 existing tests pass plus 2 new tests added.

[TheDeathConqueror]

What is the need of setting numerical entities externally? Cheers *Amit Kumar Gupta* SoloThought.com

…

On Thu, 30 Apr, 2026, 00:54 Abhishek Chauhan, ***@***.***> wrote: *abhu85* left a comment (NaturalIntelligence/fast-xml-parser#825) <#825 (comment)> I investigated this and found two related issues: *v5.7.1 (original report):* setExternalEntities() calls validateEntityName() which throws on #-prefixed entity names. This was partially fixed in v5.7.2 by passing external entities through the constructor instead (commit ebaedc0 <ebaedc0> ). *v5.7.2 (remaining issue):* While the error is gone, addEntity('#xD', '\r') is silently ignored because the EntityDecoder's NCR path intercepts #-prefixed tokens before checking the named entity map. This means &#xD; stays as literal text instead of being replaced with the registered value. Confirmed behavior across versions: - v5.5.8: addEntity('#xD', '\r') works correctly - v5.7.1: throws Invalid character '#' in entity name: "#xD" - v5.7.2: no error, but addEntity('#xD', '\r') is silently ignored Note: If you're using the AWS SDK ***@***.***/xml-builder), v5.7.2 works because the SDK provides its own entityDecoder with numericAllowed: true, bypassing this code path entirely. The issue affects direct users of addEntity with #-prefixed keys. Submitted a fix in #826 <#826> that separates #-prefixed external entities and resolves them via pre-processing before the EntityDecoder's decode pass. All 316 existing tests pass plus 2 new tests added. — Reply to this email directly, view it on GitHub <#825 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AIVYC2UG4A74XIPFLY2R2V34YJJHTAVCNFSM6AAAAACYJPGSI2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DGNBWHA2DQMBUGE> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>. You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[abhu85]

This can be resolved by enabling htmlEntities: true — numerical character references (
, A, A, etc.) are handled by the built-in EntityDecoder when this option is set:

const { XMLParser } = require('fast-xml-parser');
const parser = new XMLParser({ processEntities: true, htmlEntities: true });
const result = parser.parse('<root>test&#xD;value</root>');
// result.root === "test\rvalue" ✓

Verified on v5.7.2. No need for addEntity('#xD', '\r') — the EntityDecoder resolves both hex (&#xNNNN;) and decimal (&#NNNN;) NCRs natively with htmlEntities: true.

[amitguptagwl]

If you're new user to the library.

• check flexible-xml-parser once
• check entityDecoder property once