# Why Your SBOM Won't Parse: The Common CycloneDX and SPDX File Errors > You exported an SBOM from a generator or a vendor, and something downstream rejects it: a validator, an import tool, or your own parsing. The error message names a field you have never heard of, or worse, says nothing at all. Here are the errors that actually occur, in the order they occur, with the cause and the fix for each. And every one of them can be checked in a browser before you email the vendor: [the Vendor SBOM Checker ->](/tools/sbom-checker) tells you which of these your file has. - **Published**: 2026-10-26 - **URL**: https://vendorquals.com/blog/sbom-file-errors --- # Why Your SBOM Won't Parse: The Common CycloneDX and SPDX File Errors *You exported an SBOM from a generator or a vendor, and something downstream rejects it: a validator, an import tool, or your own parsing. The error message names a field you have never heard of, or worse, says nothing at all. Here are the errors that actually occur, in the order they occur, with the cause and the fix for each. And every one of them can be checked in a browser before you email the vendor: [the Vendor SBOM Checker ->](/tools/sbom-checker) tells you which of these your file has.* ## Key takeaways - **Most parse failures are format-detection failures.** The file is a PDF someone renamed, an Excel export, or a JSON that is neither CycloneDX nor SPDX. Detection is the first thing any tool does: CycloneDX carries `bomFormat`, SPDX carries `spdxVersion`. Missing both means the file is not an SBOM in a machine-readable format at all. - **`bom-ref` is the CycloneDX field that breaks imports most.** Components and dependencies reference each other by `bom-ref`; a missing or duplicated one breaks the dependency graph the moment an import tool tries to build it. - **A malformed purl fails silently until a vulnerability match returns nothing.** The purl schema is strict (`pkg:type/namespace/name@version`); a wrong separator or a missing version turns the component into something no database can resolve. - **NTIA element gaps are data errors, not parse errors.** The file parses fine and still fails the buyer's check: no supplier, no version, no timestamp. [The seven elements, explained ->](/blog/sbom-minimum-elements) - **The honest debugging order:** confirm it is JSON, confirm the format marker, fix the references, fix the purls, then run the element check. [Run all of it in a browser ->](/tools/sbom-checker) ## Error 1: "Not a valid SBOM" / "unknown format" **Symptom.** Your tool refuses the file with a generic message: not CycloneDX, not SPDX, cannot detect format. **Cause.** One of three things. First, the file is not JSON at all: PDF, spreadsheet, or a screenshot, which vendors do send. Second, it is JSON but neither standard: a vendor's proprietary export with components in a custom shape. Third, it is a valid export wrapped in something: a JSON envelope, a base64 blob, a zip. **Fix.** Open the file. If the first non-whitespace character is `{` or `[`, it is JSON; then look for the markers: `"bomFormat": "CycloneDX"` or `"spdxVersion": "SPDX-2.x"`. Neither present? Ask the vendor for the export again in standard CycloneDX or SPDX JSON: the formats exist so nobody has to hand-read these files: [the request language ->](/blog/how-to-request-sbom-from-vendor). If the file is a PDF or a spreadsheet, the same request, but firmer: the machine-readable formats are what FDA's guidance and the EU CRA documentation requirements mean by SBOM. ## Error 2: "missing component bom-ref" (CycloneDX) **Symptom.** A validator or import tool rejects the file with a `bom-ref` complaint, or a dependency-graph import comes out empty or broken. **Cause.** In CycloneDX, every component can carry a `bom-ref`, a string identifier that the `dependencies[]` section uses to reference it (`"ref": "..."` and `"dependsOn": ["..."]`). Two failure modes: the generator omitted `bom-ref` from components but populated dependencies (references that point nowhere), or duplicate `bom-ref` values across components (references that point at two things at once). Hand-edited SBOMs and merged exports produce the second most often. **Fix.** The bom-ref must be unique per component and consistent between the `components[]` and `dependencies[]` sections. If you generated the file yourself, re-export rather than hand-edit: generators compute refs. If a vendor sent it, it is a generator misconfiguration on their side, and the fix belongs to them: the file fails the dependency-relationship element of the NTIA minimum list as received. ## Error 3: "Invalid purl" / "package url schema syntax" **Symptom.** A validation tool flags a component's purl, or a vulnerability match silently returns nothing for components you can see are listed. **Cause.** The purl schema is `pkg:type/namespace/name@version?qualifiers`, and the parts are strict: forward slashes in fixed positions, `@` before the version, no spaces unencoded, lowercase type. The common breaks: a version appended without `@` (`pkg:npm/lodash-4.17.21`), a namespace glued to the name (`pkg:maven/org.apache.commons.text` instead of `pkg:maven/org.apache.commons/text`), or spaces and special characters unencoded. **Fix.** The correct form for a Maven artifact with a namespace is `pkg:maven/org.apache.logging.log4j/log4j-core@2.14.1`: type, then namespace, then name, then `@version`. If you are generating SBOMs, this is a generator bug to fix upstream. If a vendor's file carries malformed purls, the components will not match any advisory database: the single most consequential error on this page, because the file looks complete and checks nothing. [The element explanation ->](/blog/sbom-minimum-elements) covers why the identifier is the load-bearing field. ## Error 4: SPDX: "invalid spdxVersion" or missing packages **Symptom.** The tool recognizes SPDX but rejects the version, or imports zero packages from a file that clearly lists some. **Cause.** `spdxVersion` must be an exact, supported value (`SPDX-2.2`, `SPDX-2.3`); a typo or a vendor's invented value fails validation. Empty imports usually mean the packages live under a name the tool does not read, or the file uses a valid but ancient spec version the importer dropped. **Fix.** Ask for SPDX 2.2 or 2.3 JSON: the two versions with the deepest tool support. Both are current standards; the purl external reference (`referenceType: "purl"`) is how SPDX packages carry the identifier vulnerability databases resolve, and its absence is the same silent failure as Error 3. ## Error 5: The file parses and still fails the check **Symptom.** No parse error, but the buyer-side check comes back with gaps: no supplier, no versions, no dependency data, no timestamp. **Cause.** These are not syntax errors; they are NTIA minimum-element gaps. The file is structurally valid and informationally empty. Hand-built SBOMs almost always land here: they satisfy the tool that made them and fail the buyer that reads them. **Fix.** Send it back with the missing elements named, not with a general complaint: [how to verify a vendor's SBOM ->](/blog/vendor-sbom-verification) covers which elements matter for what, and the checker reports each gap per component. ## Frequently asked questions **How do I validate an SBOM file structure without buying anything?** Paste it into [the browser checker ->](/tools/sbom-checker): the format detection, the element check, and the OSV match run locally, nothing is stored, and the error output uses the names above. **Which formats do regulators require?** FDA's guidance recommends machine-readable SBOMs consistent with the NTIA minimum elements, with SPDX and CycloneDX as the dominant satisfying formats; the EU Cyber Resilience Act requires machine-readable documentation. Neither mandates a specific one: [the elements, explained ->](/blog/sbom-minimum-elements). **Can a file pass validation and still be useless?** Yes: that is Error 5, the most common case of all. Validation confirms the syntax; the element check confirms the content. Both are needed. **Do generators ever produce these errors?** The mature ones rarely produce Errors 1-3; hand-editing and merging are where those enter. Generators do differ on element completeness, which is why the element check exists independently of the format check. Check your file in the browser: format detection, the seven elements, and the OSV match, in one pass. [Check an SBOM ->](/tools/sbom-checker) --- *The error patterns here reflect the CycloneDX (ECMA-424) and SPDX specifications as published, the purl schema, and the NTIA minimum elements document, as last reviewed; the formats evolve, so confirm against the current spec before relying on the details. Last verified: October 2026. Have a correction or addition? [Request inclusion or a correction ->]* Source: https://vendorquals.com/blog/sbom-file-errors. This page is also served as HTML at https://vendorquals.com/blog/sbom-file-errors. --- - [All articles](https://vendorquals.com/blog)