Invalid character '#' in entity name: "#xD"

[FlowmasterHaggla]

• Are you running the latest version?

  • Have you included sample input, output, error, and expected output?
  • Have you checked if you are using correct configuration?
  • Did you try online tool?
  • Have you checked the docs for helpful APIs and examples?

  Description

  Regression in fast-xml-parser@5.7.0: parser.addEntity("#xD", "\r") succeeds, but parsing later fails with [EntityReplacer] Invalid character '#' in entity name: "#xD".

  This breaks the AWS XML protocol usage pattern (@aws-sdk/xml-builder) which registers #xD and #10 entities before parsing XML responses.

  Input

  Run with Node.js (reproduced on v22.18.0 and v24.13.0) and fast-xml-parser@5.7.0.

  Code

  const { XMLParser } = require("fast-xml-parser");
  
  const xml =
    '<?xml version="1.0" encoding="UTF-8"?>' +
    "<Tagging><TagSet>" +
    "<Tag><Key>kind</Key><Value>anamnesis</Value></Tag>" +
    "<Tag><Key>pii</Key><Value>true</Value></Tag>" +
    "<Tag><Key>retention</Key><Value>permanent</Value></Tag>" +
    "</TagSet></Tagging>";
  
  const parser = new XMLParser({
    attributeNamePrefix: "",
    processEntities: {
      enabled: true,
      maxTotalExpansions: Number.POSITIVE_INFINITY,
    },
    htmlEntities: true,
    ignoreAttributes: false,
    ignoreDeclaration: true,
    parseTagValue: false,
    trimValues: false,
    tagValueProcessor: (_, val) =>
      val.trim() === "" && val.includes("\n") ? "" : undefined,
    maxNestedTags: Number.POSITIVE_INFINITY,
  });
  
  parser.addEntity("#xD", "\r"); // succeeds
  parser.addEntity("#10", "\n"); // succeeds
  
  // throws in 5.7.0:
  const out = parser.parse(xml, true);
  console.log(out);
  
  ### Output
  
  Error: [EntityReplacer] Invalid character '#' in entity name: "#xD"
  
  ### expected data

#xD is a legal XML Character -> https://www.w3.org/TR/2006/PER-xml-20060614/
The XML should parse successfully, returning an object like:

{
Tagging: {
TagSet: {
Tag: [
{ Key: "kind", Value: "anamnesis" },
{ Key: "pii", Value: "true" },
{ Key: "retention", Value: "permanent" }
]
}
}
}

Additional context from version matrix:

• @aws-sdk/xml-builder@3.972.18 with nested fast-xml-parser@5.5.8 => works
• same setup with npm override forcing fast-xml-parser@5.7.0 => fails with error above

Would you like to work on this issue?

• Yes
• No

[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.

[benhoad]

Due to breaking changes see also: #822

[FlowmasterHaggla]

W3C XML Char:

#x9 | #xA | #xD ... should be allowed -> https://www.w3.org/TR/2006/PER-xml-20060614/

[TheDeathConqueror]

I'm traveling. So will check the issue tomorrow evening IST. Meanwhile can you please check following - are you setting numerical entities externally? The right approach is to just enable the flag. - check XML version and NCR conflict. Cheers *Amit Kumar Gupta* SoloThought.com

…

On Thu, 23 Apr, 2026, 17:24 Florian Sailer, ***@***.***> wrote: *FlowmasterHaggla* left a comment (NaturalIntelligence/fast-xml-parser#823) <#823 (comment)> W3C XML Char: #x9 | #xA | #xD ... should be allowed -> https://www.w3.org/TR/2006/PER-xml-20060614/ — Reply to this email directly, view it on GitHub <#823?email_source=notifications&email_token=AIVYC2VMGT7CKH2O5BMVVF34XH77RA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIMZQGQYTGOJUHAY2M4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOSWGM33PORSXEX3DNRUWG2Y#issuecomment-4304139481>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AIVYC2RS6JBJGNODUZE6QU34XH77RAVCNFSM6AAAAACYDUGY7GVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DGMBUGEZTSNBYGE> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/AIVYC2R5Y3SYRGV4IMWSKBD4XH77RA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIMZQGQYTGOJUHAY2M4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOSVGM33PORSXEX3JN5ZQ> and Android <https://github.com/notifications/mobile/android/AIVYC2XF3F3ZRT4D7NWNSID4XH77RA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIMZQGQYTGOJUHAY2M4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOSXGM33PORSXEX3BNZSHE33JMQ>. Download it today! You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[FlowmasterHaggla]

Thanks Amit. I checked both points.

• External numeric entities:
  Yes, in our failing path this is exactly what happens via AWS xml-builder:
  parser.addEntity("#xD", "\r") and parser.addEntity("#10", "\n").

So does @aws-sdk/xml-builder has to handle this issue ?

[amitguptagwl]

I'm not sure why are they setting them externally. I feel they're not overriding those values but keep the htmlentity flag off and setting these selective entities they need. I can't access the code but as I remember, numerical entities are by default on if you set HTML entities on (old config but still supported) and these external entities are not needed. Otherwise, you can set the object of ***@***.***/entities' to the config. Remove all HTML entities and create a map of only those 2 (if you need that hack). Better if you can join discord channel we can discuss there. Cheers *Amit Kumar Gupta* SoloThought.com

…

On Thu, 23 Apr, 2026, 18:40 Florian Sailer, ***@***.***> wrote: *FlowmasterHaggla* left a comment (NaturalIntelligence/fast-xml-parser#823) <#823 (comment)> Thanks Amit. I checked both points. - External numeric entities: Yes, in our failing path this is exactly what happens via AWS xml-builder: parser.addEntity("#xD", "\r") and parser.addEntity("#10", "\n"). So does @aws-sdk/xml-builder has to handle this issue ? — Reply to this email directly, view it on GitHub <#823?email_source=notifications&email_token=AB2WAKEN5W6W2EHYWPYFGJL4XII4VA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIMZQGQ3DEMZRG432M4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOSWGM33PORSXEX3DNRUWG2Y#issuecomment-4304623177>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AB2WAKAHWG5ALILSXSH3RC34XII4VAVCNFSM6AAAAACYDUGY7GVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DGMBUGYZDGMJXG4> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/AB2WAKBS5OJ55TNKAJZLZST4XII4XA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIMZQGQ3DEMZRG432M4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOSVGM33PORSXEX3JN5ZQ> and Android <https://github.com/notifications/mobile/android/AB2WAKH4GB54NPXO2BQ7NSD4XII4XA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIMZQGQ3DEMZRG432M4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOSXGM33PORSXEX3BNZSHE33JMQ>. Download it today! You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[psoleckimoj]

I spotted there was a breaking change in a minor release as we've experienced this issue and rolled back. Breaking changes should be major version releases only according to semvar?

MAJOR version when you make incompatible API changes (i.e. breaking)
MINOR version when you add functionality in a backward compatible manner
PATCH version when you make backward compatible bug fixes

It'd be nice if the aws module handled this as they explicitly locked their package json to use 5.5.8 and I think this is why we see a zombie security issue that keep rearing it's head.

[amitguptagwl]

@psoleckimoj I respect your suggestion. You can find that there are many unnecessary configuration present for backward compatibility only. However, major or minor release of not supporting numerical external entity anymore is debatable. Numerical entities are supported internally since v4.3.6. So it makes no sense for a project to set them externally.

[amitguptagwl]

5.7.2 is released. It contains 2 additional fixes. I hope they would not be breaking anything currently there.

Not releasing major version currently. People who want NCR support without conflict externally set numerical entities can use new options.