twentyhq/twenty · warning · Error

EntityDescriptor element is missing

Error message

EntityDescriptor element is missing

What it means

Thrown by parseSAMLMetadataFromXMLFile (parseSAMLMetadataFromXMLFile.ts:73-75) when the XML parses successfully but no EntityDescriptor element is found under any of the supported namespace prefixes (md, ns0, ns2, dsig, ds) or unprefixed. EntityDescriptor is the root element of a SAML 2.0 metadata document. Caught at line 127 and returned as `{ success: false, reason: 'EntityDescriptor element is missing' }`.

Source

Thrown at packages/twenty-front/src/modules/settings/security/utils/parseSAMLMetadataFromXMLFile.ts:75

  if (error instanceof Error) return error.message;
  return 'Unknown parsing error';
};

export const parseSAMLMetadataFromXMLFile = (
  xmlString: string,
):
  | { success: true; data: z.infer<typeof validator> }
  | { success: false; reason: string } => {
  try {
    const parser = new DOMParser();
    const xmlDoc = parser.parseFromString(xmlString, 'application/xml');
    if (xmlDoc.getElementsByTagName('parsererror').length > 0) {
      throw new Error('File is not valid XML');
    }

    const entityDescriptor = getByPrefixAndKey(xmlDoc, 'EntityDescriptor');
    if (!entityDescriptor)
      throw new Error('EntityDescriptor element is missing');

    const IDPSSODescriptor = getByPrefixAndKey(xmlDoc, 'IDPSSODescriptor');
    if (!IDPSSODescriptor)
      throw new Error('IDPSSODescriptor element is missing');

    const keyDescriptors = getByPrefixAndKey(IDPSSODescriptor, 'KeyDescriptor');
    if (!keyDescriptors) throw new Error('KeyDescriptor element is missing');

    const keyInfo = getByPrefixAndKey(keyDescriptors, 'KeyInfo');
    if (!keyInfo) throw new Error('KeyInfo element is missing');

    const x509Data = getByPrefixAndKey(keyInfo, 'X509Data');
    if (!x509Data) throw new Error('X509Data element is missing');

    const x509Certificate = getByPrefixAndKey(
      x509Data,
      'X509Certificate',
    )?.textContent?.trim();

View on GitHub (pinned to 1f5dd2bbd2)

Solutions

  1. Upload the IdP metadata XML (must contain <EntityDescriptor> as root).
  2. If the IdP uses an unusual namespace prefix, preprocess the XML to normalize prefixes or extend allPrefix.
  3. Verify with the IdP vendor that the file is the metadata export.
  4. Inspect the XML root tag to confirm it is EntityDescriptor.
Defensive patterns

Strategy: validation

Validate before calling

// Pre-check for the EntityDescriptor root before parsing metadata
const doc = new DOMParser().parseFromString(xmlString, 'application/xml');
const hasEntityDescriptor =
  doc.getElementsByTagName('EntityDescriptor').length > 0 ||
  ['md', 'ns0', 'ns2', 'dsig', 'ds'].some((p) =>
    doc.getElementsByTagName(`${p}:EntityDescriptor`).length > 0,
  );
if (!hasEntityDescriptor) {
  setFormError(t`Metadata must contain an EntityDescriptor element`);
}

Type guard

const hasEntityDescriptor = (s: string): boolean => {
  const doc = new DOMParser().parseFromString(s, 'application/xml');
  return ['md', 'ns0', 'ns2', 'dsig', 'ds', '']
    .some((p) => doc.getElementsByTagName(p ? `${p}:EntityDescriptor` : 'EntityDescriptor').length > 0);
};

Try / catch

// Parser returns { success: false, reason } — handle accordingly
const result = parseSAMLMetadataFromXMLFile(xmlString);
if (!result.success && result.reason === 'EntityDescriptor element is missing') {
  setFormError(t`Upload IdP metadata containing EntityDescriptor`);
}

Prevention

When it happens

Trigger: Uploaded valid XML that is not a SAML metadata document — e.g. a SPARQL/eduserv/other XML payload, or a SAML metadata using an unsupported namespace prefix not in allPrefix.

Common situations: Uploading a service-provider metadata file instead of identity-provider metadata; IdP using a custom namespace prefix not in [md, ns0, ns2, dsig, ds]; uploading an AuthnRequest XML instead of metadata.

Related errors

AI-assisted analysis of twentyhq/twenty@1f5dd2bbd2 (2026-08-12). Data as JSON: /api/errors/a9190de4d405b38e. Report an issue: GitHub.