# SEC XBRL parse failed on a taxonomy extension

## TL;DR
When XBRL parsing breaks on a taxonomy extension, the base US-GAAP taxonomy is usually fine and the company's custom extension schema is what fails to load, often because the extension files were not downloaded alongside the instance document. Pull the full filing index so the extension schema and linkbases come down with the instance, then re-parse. If the extension stays broken, the SEC's companyfacts JSON API gives you the same reported facts without touching XBRL at all.

## The error
```text
XBRL parse error: taxonomy extension failed to load
company extension schema [cik]-2026.xsd not found; 0 facts extracted
```

## When this helps
- an XBRL parser extracts zero facts or throws on the extension schema
- a briefing agent needs custom company metrics that live in extension tags
- validating a new XBRL intake pipeline against real filings
- deciding between parsing XBRL and using the companyfacts API

## When it doesn't
- the base us-gaap parse also fails; that is a corrupt download, re-fetch the instance
- you need the extension's calculation relationships; the JSON API flattens those
- the filing predates XBRL mandates; older filings have no instance document at all

## Works with
python 3.9+ with arelle (pip install arelle-release) or lxml for manual parsing. data.sec.gov companyfacts API as of 2026.

## Steps
### 1. Prove the base taxonomy parses and the extension is the problem
```python
import requests
s = requests.Session()
s.headers.update({"User-Agent": "IntelBriefingBot/1.0"})
r = s.get("https://www.sec.gov/Archives/edgar/data/[cik]/[accession]/[instance]-2026.xml", timeout=60)
open("instance.xml", "wb").write(r.content)
print("downloaded", len(r.content), "bytes")
print("next: parse with only us-gaap namespace facts counted")
```
Expected: The instance file on disk. Counting us-gaap facts separately from extension facts tells you which half breaks.

### 2. Download the extension files from the filing index
```bash
curl -s -A "IntelBriefingBot/1.0" "https://www.sec.gov/Archives/edgar/data/[cik]/[accession]/" -o index.html
curl -s -A "IntelBriefingBot/1.0" "https://www.sec.gov/Archives/edgar/data/[cik]/[accession]/[cik]-2026.xsd" -o ext.xsd -w "schema HTTP %{http_code}\n"
curl -s -A "IntelBriefingBot/1.0" "https://www.sec.gov/Archives/edgar/data/[cik]/[accession]/[cik]-2026_cal.xml" -o ext_cal.xml -w "calc linkbase HTTP %{http_code}\n"
```
Expected: HTTP 200 on the schema and linkbase files. Extension schemas live next to the instance in the same filing directory; parsers fail when you fetch the instance alone.

### 3. Re-parse with the extension files present
```python
from arelle import Cntlr
cntlr = Cntlr.Cntlr()
model = cntlr.modelManager.modelXbrl
model.load("instance.xml")
print("facts loaded:", len(model.facts))
print("extension facts:", sum(1 for f in model.facts if "us-gaap" not in str(f.qname.namespaceURI)))
```
Expected: A fact count well above zero with extension facts included. If arelle still errors, read its message: a 404 inside the schema usually means one more linkbase file is missing from the download set.

### 4. Fall back to the companyfacts JSON API
```bash
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(list(d["facts"]["us-gaap"].keys())[:5])"
```
Expected: HTTP 200 and a list of tag names. The SEC pre-parses every filing into this JSON, so it sidesteps extension problems entirely for standard analysis.

## Other ways people phrase this
### xbrl taxonomy extension schema not found
The missing-file form. Extension schemas are per-filing; always download the filing's own index companions.

### arelle extension parse error sec filing
Arelle is strict about schema resolution. Its error names the missing file; fetch it from the filing directory.

### 0 facts extracted xbrl 10-k
Total failure usually means the instance never parsed, not an extension issue. Check the download before blaming the taxonomy.

## Why it happens
Filers define company-specific metrics in an extension taxonomy: a schema plus linkbases stored beside the instance document in the filing directory. Parsers resolve those by relative reference, so downloading only the instance leaves dangling references and the parse fails. The base US-GAAP taxonomy is remote and stable; the extension is local to the filing and fragile.

## Edge cases
- Some filers reference prior-year extension schemas; if the current filing's schema 404s, check whether the instance points at last year's file.
- The companyfacts API lags new filings by a short delay; for today's filing, parse the instance directly.
- Extension labels are filer-defined prose; two companies' custom revenue tags are not comparable without reading the label linkbase.
- Amended filings (10-K/A) ship new extension files; never mix an original instance with an amended schema.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_8n89H1EhQCfER6QAdQ3-Jg