RuntimeError: Couldn't resolve #exLinkSrv2, the address table is empty

[caufieldjh]

I encountered a RuntimeError when attempting to retrieve metadata from a PMID (https://pubmed.ncbi.nlm.nih.gov/12112053/)

$ just fetch-reference 12112053
uv run linkml-reference-validator cache reference 12112053
Fetching 12112053...
╭─────────────────────────────────────────────────────────────────────────────────────────── Traceback (most recent call last) ───────────────────────────────────────────────────────────────────────────────────────────╮
│ /home/harry/dismech/.venv/lib/python3.13/site-packages/linkml_reference_validator/cli/cache.py:76 in reference_command                                                                                                  │
│                                                                                                                                                                                                                         │
│    73 │                                                                                        ╭────────────────────────────────────────────────── locals ───────────────────────────────────────────────────╮          │
│    74 │   typer.echo(f"Fetching {reference_id}...")                                            │    cache_dir = None                                                                                         │          │
│    75 │                                                                                        │       config = ReferenceValidationConfig(                                                                   │          │
│ ❱  76 │   reference = fetcher.fetch(reference_id, force_refresh=force)                         │                │   cache_dir=PosixPath('references_cache'),                                                 │          │
│    77 │                                                                                        │                │   reference_base_dir=None,                                                                 │          │
│    78 │   if reference:                                                                        │                │   rate_limit_delay=0.5,                                                                    │          │
│    79 │   │   typer.echo(f"Successfully cached {reference_id}")                                │                │   email='linkml-reference-validator@example.com',                                          │          │
│                                                                                                │                │   supporting_text_regex=None,                                                              │          │
│                                                                                                │                │   text_group=1,                                                                            │          │
│                                                                                                │                │   ref_group=2,                                                                             │          │
│                                                                                                │                │   reference_prefix_map={},                                                                 │          │
│                                                                                                │                │   skip_prefixes=['SRA', 'BIOPROJECT'],                                                     │          │
│                                                                                                │                │   unknown_prefix_severity=<ValidationSeverity.WARNING: 'WARNING'>                          │          │
│                                                                                                │                )                                                                                            │          │
│                                                                                                │  config_file = None                                                                                         │          │
│                                                                                                │      fetcher = <linkml_reference_validator.etl.reference_fetcher.ReferenceFetcher object at 0x7f9616be6ba0> │          │
│                                                                                                │        force = False                                                                                        │          │
│                                                                                                │ reference_id = '12112053'                                                                                   │          │
│                                                                                                │      verbose = False                                                                                        │          │
│                                                                                                ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────╯          │
│                                                                                                                                                                                                                         │
│ /home/harry/dismech/.venv/lib/python3.13/site-packages/linkml_reference_validator/etl/reference_fetcher.py:104 in fetch                                                                                                 │
│                                                                                                                                                                                                                         │
│   101 │   │   # Parse identifier and fetch                                                                                                                                                                              │
│   102 │   │   _, identifier = self._parse_reference_id(normalized_reference_id)                                                                                                                                         │
│   103 │   │   source = source_class()                                                                                                                                                                                   │
│ ❱ 104 │   │   content = source.fetch(identifier, self.config)                                                                                                                                                           │
│   105 │   │                                                                                                                                                                                                             │
│   106 │   │   if content:                                                                                                                                                                                               │
│   107 │   │   │   self._cache[normalized_reference_id] = content                                                                                                                                                        │
│                                                                                                                                                                                                                         │
│ ╭──────────────────────────────────────────────────────── locals ────────────────────────────────────────────────────────╮                                                                                              │
│ │                       _ = 'PMID'                                                                                       │                                                                                              │
│ │                  cached = None                                                                                         │                                                                                              │
│ │           force_refresh = False                                                                                        │                                                                                              │
│ │              identifier = '12112053'                                                                                   │                                                                                              │
│ │ normalized_reference_id = 'PMID:12112053'                                                                              │                                                                                              │
│ │            reference_id = '12112053'                                                                                   │                                                                                              │
│ │                    self = <linkml_reference_validator.etl.reference_fetcher.ReferenceFetcher object at 0x7f9616be6ba0> │                                                                                              │
│ │                  source = <linkml_reference_validator.etl.sources.pmid.PMIDSource object at 0x7f9616be6e40>            │                                                                                              │
│ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯                                                                                              │
│                                                                                                                                                                                                                         │
│ /home/harry/dismech/.venv/lib/python3.13/site-packages/linkml_reference_validator/etl/sources/pmid.py:128 in fetch                                                                                                      │
│                                                                                                                                                                                                                         │
│   125 │   │   doi = record.get("DOI", "")                                                                                                                                                                               │
│   126 │   │                                                                                                                                                                                                             │
│   127 │   │   abstract = self._fetch_abstract(pmid, config)                                                                                                                                                             │
│ ❱ 128 │   │   full_text, content_type = self._fetch_pmc_fulltext(pmid, config)                                                                                                                                          │
│   129 │   │                                                                                                                                                                                                             │
│   130 │   │   if full_text:                                                                                                                                                                                             │
│   131 │   │   │   content: Optional[str] = f"{abstract}\n\n{full_text}" if abstract else full_                                                                                                                          │
│                                                                                                                                                                                                                         │
│ ╭────────────────────────────────────────────────────────────────────────────────────────────────────── locals ───────────────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ │   abstract = '1. Ann Neurol. 2002 Jul;52(1):95-9. doi: 10.1002/ana.10214.\n\nAdenine nucleotide '+1377                                                                                                              │ │
│ │    authors = ['Jordens EZ', 'Palmieri L', 'Huizing M', 'van den Heuvel LP', 'Sengers RC', 'Dörner A', 'Ruitenbeek W', 'Trijbels FJ', 'Valsson J', 'Sigfusson G', ... +2]                                            │ │
│ │     config = ReferenceValidationConfig(                                                                                                                                                                             │ │
│ │              │   cache_dir=PosixPath('references_cache'),                                                                                                                                                           │ │
│ │              │   reference_base_dir=None,                                                                                                                                                                           │ │
│ │              │   rate_limit_delay=0.5,                                                                                                                                                                              │ │
│ │              │   email='linkml-reference-validator@example.com',                                                                                                                                                    │ │
│ │              │   supporting_text_regex=None,                                                                                                                                                                        │ │
│ │              │   text_group=1,                                                                                                                                                                                      │ │
│ │              │   ref_group=2,                                                                                                                                                                                       │ │
│ │              │   reference_prefix_map={},                                                                                                                                                                           │ │
│ │              │   skip_prefixes=['SRA', 'BIOPROJECT'],                                                                                                                                                               │ │
│ │              │   unknown_prefix_severity=<ValidationSeverity.WARNING: 'WARNING'>                                                                                                                                    │ │
│ │              )                                                                                                                                                                                                      │ │
│ │        doi = '10.1002/ana.10214'                                                                                                                                                                                    │ │
│ │     handle = <http.client.HTTPResponse object at 0x7f9616da7d60>                                                                                                                                                    │ │
│ │ identifier = '12112053'                                                                                                                                                                                             │ │
│ │    journal = 'Ann Neurol'                                                                                                                                                                                           │ │
│ │       pmid = '12112053'                                                                                                                                                                                             │ │
│ │     record = {'Item': [], 'Id': '12112053', 'PubDate': '2002 Jul', 'EPubDate': '', 'Source': 'Ann Neurol', 'AuthorList': ['Jordens EZ', 'Palmieri L', 'Huizing M', 'van den Heuvel LP', 'Sengers RC', 'Dörner A',   │ │
│ │              'Ruitenbeek W', 'Trijbels FJ', 'Valsson J', 'Sigfusson G', 'Palmieri F', 'Smeitink JA'], 'LastAuthor': 'Smeitink JA', 'Title': 'Adenine nucleotide translocator 1 deficiency associated with Sengers   │ │
│ │              syndrome.', 'Volume': '52', 'Issue': '1', 'Pages': '95-9', 'LangList': ['English'], 'NlmUniqueID': '7707449', 'ISSN': '0364-5134', 'ESSN': '', 'PubTypeList': ['Journal Article'], 'RecordStatus':     │ │
│ │              'PubMed - indexed for MEDLINE', 'PubStatus': 'ppublish', 'ArticleIds': {'pubmed': ['12112053'], 'medline': [], 'doi': '10.1002/ana.10214'}, 'DOI': '10.1002/ana.10214', 'History': {'pubmed':          │ │
│ │              ['2002/07/12 10:00'], 'medline': ['2002/08/01 10:01'], 'entrez': '2002/07/12 10:00'}, 'References': [], 'HasAbstract': IntegerElement(1, attributes={}), 'PmcRefCount': IntegerElement(0,              │ │
│ │              attributes={}), 'FullJournalName': 'Annals of neurology', 'ELocationID': '', 'SO': '2002 Jul;52(1):95-9'}                                                                                              │ │
│ │    records = [{'Item': [], 'Id': '12112053', 'PubDate': '2002 Jul', 'EPubDate': '', 'Source': 'Ann Neurol', 'AuthorList': ['Jordens EZ', 'Palmieri L', 'Huizing M', 'van den Heuvel LP', 'Sengers RC', 'Dörner A',  │ │
│ │              'Ruitenbeek W', 'Trijbels FJ', 'Valsson J', 'Sigfusson G', 'Palmieri F', 'Smeitink JA'], 'LastAuthor': 'Smeitink JA', 'Title': 'Adenine nucleotide translocator 1 deficiency associated with Sengers   │ │
│ │              syndrome.', 'Volume': '52', 'Issue': '1', 'Pages': '95-9', 'LangList': ['English'], 'NlmUniqueID': '7707449', 'ISSN': '0364-5134', 'ESSN': '', 'PubTypeList': ['Journal Article'], 'RecordStatus':     │ │
│ │              'PubMed - indexed for MEDLINE', 'PubStatus': 'ppublish', 'ArticleIds': {'pubmed': ['12112053'], 'medline': [], 'doi': '10.1002/ana.10214'}, 'DOI': '10.1002/ana.10214', 'History': {'pubmed':          │ │
│ │              ['2002/07/12 10:00'], 'medline': ['2002/08/01 10:01'], 'entrez': '2002/07/12 10:00'}, 'References': [], 'HasAbstract': IntegerElement(1, attributes={}), 'PmcRefCount': IntegerElement(0,              │ │
│ │              attributes={}), 'FullJournalName': 'Annals of neurology', 'ELocationID': '', 'SO': '2002 Jul;52(1):95-9'}]                                                                                             │ │
│ │       self = <linkml_reference_validator.etl.sources.pmid.PMIDSource object at 0x7f9616be6e40>                                                                                                                      │ │
│ │      title = 'Adenine nucleotide translocator 1 deficiency associated with Sengers syndrome.'                                                                                                                       │ │
│ │       year = '2002'                                                                                                                                                                                                 │ │
│ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
│                                                                                                                                                                                                                         │
│ /home/harry/dismech/.venv/lib/python3.13/site-packages/linkml_reference_validator/etl/sources/pmid.py:198 in _fetch_pmc_fulltext                                                                                        │
│                                                                                                                                                                                                                         │
│   195 │   │   Returns:                                                                         ╭────────────────────────────────────────── locals ──────────────────────────────────────────╮                           │
│   196 │   │   │   Tuple of (full_text, content_type)                                           │ config = ReferenceValidationConfig(                                                        │                           │
│   197 │   │   """                                                                              │          │   cache_dir=PosixPath('references_cache'),                                      │                           │
│ ❱ 198 │   │   pmcid = self._get_pmcid(pmid, config)                                            │          │   reference_base_dir=None,                                                      │                           │
│   199 │   │   if not pmcid:                                                                    │          │   rate_limit_delay=0.5,                                                         │                           │
│   200 │   │   │   return None, "no_pmc"                                                        │          │   email='linkml-reference-validator@example.com',                               │                           │
│   201                                                                                          │          │   supporting_text_regex=None,                                                   │                           │
│                                                                                                │          │   text_group=1,                                                                 │                           │
│                                                                                                │          │   ref_group=2,                                                                  │                           │
│                                                                                                │          │   reference_prefix_map={},                                                      │                           │
│                                                                                                │          │   skip_prefixes=['SRA', 'BIOPROJECT'],                                          │                           │
│                                                                                                │          │   unknown_prefix_severity=<ValidationSeverity.WARNING: 'WARNING'>               │                           │
│                                                                                                │          )                                                                                 │                           │
│                                                                                                │   pmid = '12112053'                                                                        │                           │
│                                                                                                │   self = <linkml_reference_validator.etl.sources.pmid.PMIDSource object at 0x7f9616be6e40> │                           │
│                                                                                                ╰────────────────────────────────────────────────────────────────────────────────────────────╯                           │
│                                                                                                                                                                                                                         │
│ /home/harry/dismech/.venv/lib/python3.13/site-packages/linkml_reference_validator/etl/sources/pmid.py:225 in _get_pmcid                                                                                                 │
│                                                                                                                                                                                                                         │
│   222 │   │   time.sleep(config.rate_limit_delay)                                              ╭────────────────────────────────────────── locals ──────────────────────────────────────────╮                           │
│   223 │   │                                                                                    │ config = ReferenceValidationConfig(                                                        │                           │
│   224 │   │   handle = Entrez.elink(dbfrom="pubmed", db="pmc", id=pmid, linkname="pubmed_pmc") │          │   cache_dir=PosixPath('references_cache'),                                      │                           │
│ ❱ 225 │   │   result = Entrez.read(handle)                                                     │          │   reference_base_dir=None,                                                      │                           │
│   226 │   │   handle.close()                                                                   │          │   rate_limit_delay=0.5,                                                         │                           │
│   227 │   │                                                                                    │          │   email='linkml-reference-validator@example.com',                               │                           │
│   228 │   │   if result and result[0].get("LinkSetDb"):                                        │          │   supporting_text_regex=None,                                                   │                           │
│                                                                                                │          │   text_group=1,                                                                 │                           │
│                                                                                                │          │   ref_group=2,                                                                  │                           │
│                                                                                                │          │   reference_prefix_map={},                                                      │                           │
│                                                                                                │          │   skip_prefixes=['SRA', 'BIOPROJECT'],                                          │                           │
│                                                                                                │          │   unknown_prefix_severity=<ValidationSeverity.WARNING: 'WARNING'>               │                           │
│                                                                                                │          )                                                                                 │                           │
│                                                                                                │ handle = <http.client.HTTPResponse object at 0x7f9616cbab30>                               │                           │
│                                                                                                │   pmid = '12112053'                                                                        │                           │
│                                                                                                │   self = <linkml_reference_validator.etl.sources.pmid.PMIDSource object at 0x7f9616be6e40> │                           │
│                                                                                                ╰────────────────────────────────────────────────────────────────────────────────────────────╯                           │
│                                                                                                                                                                                                                         │
│ /home/harry/dismech/.venv/lib/python3.13/site-packages/Bio/Entrez/__init__.py:529 in read                                                                                                                               │
│                                                                                                                                                                                                                         │
│   526 │   from .Parser import DataHandler                                                      ╭───────────────────────────────── locals ─────────────────────────────────╮                                             │
│   527 │                                                                                        │        escape = False                                                    │                                             │
│   528 │   handler = DataHandler(validate, escape, ignore_errors)                               │       handler = <Bio.Entrez.Parser.DataHandler object at 0x7f9616c64a50> │                                             │
│ ❱ 529 │   record = handler.read(source)                                                        │ ignore_errors = False                                                    │                                             │
│   530 │   return record                                                                        │        source = <http.client.HTTPResponse object at 0x7f9616cbab30>      │                                             │
│   531                                                                                          │      validate = True                                                     │                                             │
│   532                                                                                          ╰──────────────────────────────────────────────────────────────────────────╯                                             │
│                                                                                                                                                                                                                         │
│ /home/harry/dismech/.venv/lib/python3.13/site-packages/Bio/Entrez/Parser.py:405 in read                                                                                                                                 │
│                                                                                                                                                                                                                         │
│    402 │   │   if stream.read(0) != b"":                                                        ╭───────────────────────────── locals ──────────────────────────────╮                                                   │
│    403 │   │   │   raise TypeError("file should be opened in binary mode")                      │   self = <Bio.Entrez.Parser.DataHandler object at 0x7f9616c64a50> │                                                   │
│    404 │   │   try:                                                                             │ source = <http.client.HTTPResponse object at 0x7f9616cbab30>      │                                                   │
│ ❱  405 │   │   │   self.parser.ParseFile(stream)                                                │ stream = <http.client.HTTPResponse object at 0x7f9616cbab30>      │                                                   │
│    406 │   │   except expat.ExpatError as e:                                                    ╰───────────────────────────────────────────────────────────────────╯                                                   │
│    407 │   │   │   if self.parser.StartElementHandler:                                                                                                                                                                  │
│    408 │   │   │   │   # We saw the initial <!xml declaration, so we can be sure that                                                                                                                                   │
│                                                                                                                                                                                                                         │
│ in EndElement:475                                                                                                                                                                                                       │
│                                                                                                                                                                                                                         │
│ /home/harry/dismech/.venv/lib/python3.13/site-packages/Bio/Entrez/Parser.py:818 in endErrorElementHandler                                                                                                               │
│                                                                                                                                                                                                                         │
│    815 │   │   if data == "":                                                                   ╭─────────────────────────────── locals ────────────────────────────────╮                                               │
│    816 │   │   │   return                                                                       │    data = "Couldn't resolve #exLinkSrv2, the address table is empty." │                                               │
│    817 │   │   if self.ignore_errors is False:                                                  │ element = []                                                          │                                               │
│ ❱  818 │   │   │   raise RuntimeError(data)                                                     │    self = <Bio.Entrez.Parser.DataHandler object at 0x7f9616c64a50>    │                                               │
│    819 │   │   self.data = []                                                                   │     tag = 'ERROR'                                                     │                                               │
│    820 │   │   value = ErrorElement(data, tag)                                                  ╰───────────────────────────────────────────────────────────────────────╯                                               │
│    821 │   │   if element is None:                                                                                                                                                                                      │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
RuntimeError: Couldn't resolve #exLinkSrv2, the address table is empty.
error: Recipe `fetch-reference` failed on line 336 with exit code 1

Looks like an issue with finding or parsing the PMC ID?

[github-actions]

Issue Summary

This error occurs when attempting to fetch metadata for PMID:12112053, specifically during the PMCID lookup step via NCBI's Entrez elink API.

The Paper

Title: "Adenine nucleotide translocator 1 deficiency associated with Sengers syndrome."
Authors: Jordens EZ, Palmieri L, Huizing M, et al.
Journal: Annals of Neurology, 2002 Jul;52(1):95-9
DOI: 10.1002/ana.10214
PubMed: https://pubmed.ncbi.nlm.nih.gov/12112053/

Root Cause Analysis

The error occurs in pmid.py:225 in the _get_pmcid() method:

handle = Entrez.elink(dbfrom="pubmed", db="pmc", id=pmid, linkname="pubmed_pmc")
result = Entrez.read(handle)  # <-- RuntimeError thrown here

Error message: "Couldn't resolve #exLinkSrv2, the address table is empty."

This is an NCBI E-utilities XML parsing error from BioPython's Entrez parser, not a code bug. The error indicates that NCBI's elink API returned malformed XML with an unresolved entity reference (#exLinkSrv2).

Why This Happens

This specific PMID was published in 2002, predating PubMed Central's open access mandate. Looking at the metadata in the traceback:

• 'PmcRefCount': IntegerElement(0, ...) - indicates 0 PMC references
• The paper has no PMC full-text version available

When there's no PMC link, NCBI's API sometimes returns error XML instead of an empty result, causing BioPython's strict XML parser to fail.

Affected Papers

This likely affects:

1. Older papers (pre-2008) without PMC versions
2. Closed-access journals not participating in PMC
3. Papers where PMC linking data is incomplete/corrupted
4. Temporary NCBI database sync issues

Similar Issues

Related to issue #28 (closed) which dealt with unsupported prefixes, and #34 (closed) which fixed severity level handling. This is a variant where:

• The prefix (PMID) IS supported
• The abstract fetch succeeds
• Only the PMC fulltext lookup fails

Recommended Solutions

Option 1: Catch and handle elink errors gracefully (Recommended)

Modify _get_pmcid() in pmid.py:274-276 to catch RuntimeError:

try:
    result = Entrez.read(handle)
except RuntimeError as e:
    if "Couldn't resolve" in str(e) or "address table is empty" in str(e):
        # NCBI elink error, treat as no PMC version available
        return None
    raise  # Re-raise other RuntimeErrors

Option 2: Use ignore_errors flag in Entrez.read()

result = Entrez.read(handle, validate=False)

However, this may mask other legitimate XML parsing issues.

Option 3: Fallback to ID Converter API

When elink fails, try NCBI's ID Converter API as a backup for PMID→PMCID translation.

Testing Recommendations

Add test cases for:

• ✅ PMID with PMC version (e.g., modern open access papers)
• ✅ PMID without PMC version (e.g., 12112053)
• ✅ PMID with broken elink data

Workaround (Current)

Users encountering this error can:

1. Use DOI instead of PMID if available: DOI:10.1002/ana.10214
2. Add PMID to skip_prefixes temporarily (though this disables all PMID validation)
3. Cache only the abstract by modifying _fetch_pmc_fulltext() to not raise on errors

---

Impact: This bug prevents validation of any data file containing references to PMIDs without PMC full-text versions, which includes a significant portion of biomedical literature published before ~2008 and closed-access journals.

Priority: Medium-High - affects legitimate use cases with correctly formatted data

[caufieldjh]

Versions:
linkml 1.9.5
linkml-data-qc 0.1.0
linkml-reference-validator 0.1.4rc8
linkml-renderer 0.3.1
linkml-runtime 1.9.5
linkml-term-validator 0.2.1