xbrl schema reference 404 old taxonomy year error

XBRL schema reference 404s on an old taxonomy year

TL;DR

Schema references 404 when the instance points at a taxonomy year the SEC no longer hosts at that URL, common with older filings whose schemas moved or were superseded. The facts in the instance are still good; only the schema resolution fails. Fix it by fetching the schema from the filing's own directory or the SEC's archived taxonomy location, and validate the facts against the companyfacts API when the schema stays unreachable.

The error

XBRL schema 404
schemaRef https://xbrl.sec.gov/us-gaap/2018/elts/us-gaap-2018-01-31.xsd returned 404; parse failed

When this helps

• XBRL parsing fails on schema 404s for old taxonomy years
• older filings will not parse with current tools
• building a historical XBRL pipeline
• validating old instance data

When it doesn't

• the instance itself is corrupt; a good schema will not fix bad facts
• you need the old taxonomy's definitions; archived taxonomies may differ subtly from current ones
• the filing is current-year; its schema should resolve, check the URL

Works with

python 3.8+ with re; arelle with local taxonomy packages. SEC taxonomy hosting changes over time.

Steps

1. Read the schemaRef from the instance to see what it wants

import re
xml = open("instance.xml").read()
refs = re.findall(r'schemaRef.{0,200}?href="([^"]+)"', xml)
print("schema refs:", refs[:3])

Expected: The schema URLs. Old years point at locations that may have moved; the filing directory often carries a local copy.

2. Check the filing directory for a local schema copy

curl -s -A "IntelBriefingBot/1.0" "https://www.sec.gov/Archives/edgar/data/[cik]/[accession]/" -o index.html
grep -o "[a-z0-9_.-]*\.xsd" index.html | sort -u | head -10

Expected: Local schema filenames. Filings sometimes bundle the exact schema version the instance references.

3. Point the parser at the local schema

import re
xml = open("instance.xml").read()
local = "./[cik]-2026.xsd"
print("schema files available locally; configure the parser's schema cache to prefer the filing directory")
print("arelle: use --packages or a local taxonomy cache directory")

Expected: A parser configuration that resolves schemas locally. Local resolution also speeds up every future parse.

4. Validate facts against the companyfacts API as a cross-check

curl -s -A "IntelBriefingBot/1.0" "https://data.sec.gov/api/xbrl/companyfacts/CIK[cik-padded].json" -o facts.json -w "HTTP %{http_code}\n"
python3 -c "import json; d=json.load(open("facts.json")); print("api facts ok")"

Expected: HTTP 200. The API carries the same reported facts independent of schema hosting, which confirms the instance data is sound.

Other ways people phrase this

xbrl schema 404 old taxonomy

Old years move. The filing directory or a local taxonomy cache is the fix.

us-gaap 2018 schema not found

Year-specific schemas get archived. Pin the parser to a local copy.

schemaref 404 sec xbrl parse

The reference is stale, not the data. Resolve locally and cross-check with the API.

Why it happens

Taxonomy schemas are versioned by year and hosted at versioned URLs. Old filings reference old URLs that get moved or retired, so the schemaRef 404s while the instance facts remain valid. Parsers that require schema resolution fail; parsers with a local taxonomy cache or lenient resolution succeed.

Edge cases

• Taxonomy definitions change between years; compare old-year facts with care.
• Some old filings reference schemas that were never public; the companyfacts API is the fallback.
• Keep a local taxonomy archive for every year you parse; re-downloading per filing is wasteful.
• Amended old filings may reference newer schemas than the original; use the amendment's refs.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_23M7U647FC0n-OUgmDsIRA