Reactome pathway import is broken: the legacy BioPAX exporter returns HTTP 200 with an error body, and the client shows an XML parse error

Start at BioModelEditorPathwayCommonsPanel.showPathway() in vcell-client (around line 386) where XmlUtil.stringToXML is called on the downloaded body, and at ClientDownloader.downloadBytes in vcell-core/src/main/java/org/vcell/util/network/ClientDownloader.java (around line 53) which ignores statusCode(). Decide scope first: the minimal fix is status/body validation before parsing plus a readable 'Reactome unavailable' message; the larger questions (changing downloadBytes for all callers, migrating to ContentService) are flagged as open decisions in the issue. Done looks like a Reactome outage producing a clear message instead of 'source document is not well-formed', with the test-side precedent in PathwaySearchTest.assumeXmlOrSkip (#2081) as the reference behavior.

What users see

Pathways → search → Show Pathway on any Reactome result fails with

source document is not well-formed
Content is not allowed in prolog.

Nothing imports. The message says nothing about Reactome, so it reads as a VCell bug or a corrupt model.

Why

Reactome's legacy BioPAX exporter — the endpoint the import uses — has been failing on
their side since sometime after 2026-09-08, and is still failing as of 2026-09-14:

$ curl -i https://reactome.org/ReactomeRESTfulAPI/RESTfulWS/biopaxExporter/Level2/5683177
HTTP/2 200
content-type: text/plain;charset=UTF-8

Error in biopax exporter: No operations allowed after connection closed.

Every pathway id, Level2 and Level3 alike. That is a dead database connection in their
backend, reported as HTTP 200 instead of 5xx.

Why the message is cryptic rather than "Reactome is unavailable"

In BioModelEditorPathwayCommonsPanel.showPathway()
(vcell-client/src/main/java/cbit/vcell/client/desktop/biomodel/BioModelEditorPathwayCommonsPanel.java:386):

String contentString = ClientDownloader.downloadBytes(url, Duration.ofSeconds(20));
org.jdom2.Document jdomDocument = XmlUtil.stringToXML(contentString, null);   // throws here
org.jdom2.Element rootElement = jdomDocument.getRootElement();
String errorCode = rootElement.getChildText(ERROR_CODE_TAG);                  // never reached
if (errorCode != null) { throw new RuntimeException("Failed to access " + url + " ..."); }

Three things line up badly:

1. ClientDownloader.downloadBytes returns response.body() whatever the status
   (vcell-core/src/main/java/org/vcell/util/network/ClientDownloader.java:53) — it never
   inspects statusCode(), so an error page or error text is handed back as if it were content.
2. XmlUtil.stringToXML throws RuntimeException("source document is not well-formed...")
   on the plain-text body, which is what the user ends up seeing.
3. The error_code check that was meant to catch a Reactome-side failure sits after the
   parse, so it can never run for this class of failure — it only ever caught an error that
   Reactome reported as well-formed XML.

Suggested work

• Report the outage honestly. Check the HTTP status and the body before parsing, and
  show something like "Reactome is not responding correctly right now — please try again
  later" instead of an XML parse error. The test-side equivalent landed in #2081
  (assumeXmlOrSkip): at this endpoint a non-XML body is Reactome's failure, since a wrong
  request of ours comes back 404.

• Decide whether ClientDownloader.downloadBytes should keep returning the body on a
  non-2xx status. Every caller inherits this trap; it is the same defect that made the
  PathwaySearchTest guard ineffective twice (see #1819 and #2081).

• Decide what to do about the source. The successor is the Reactome Content Service
  (https://github.com/reactome/content-service), described as:

  Reactome Content Service API: The primary RESTful API allows you to query the live Graph
  Database. While much of the direct API payload is delivered in JSON format, the web
  services explicitly support pulling out standardized community formats—including BioPAX,
  SBML, and SBGN—for specific pathway identifiers

  The BioPAX half of that does not hold today, and it is worth knowing before anyone plans
  a port. Checked against the service's own live OpenAPI spec
  (https://reactome.org/ContentService/v3/api-docs, fetched 2026-09-14): the string
  biopax appears zero times, and the only per-identifier export paths are

  /exporter/event/{identifier}.sbml
  /exporter/event/{identifier}.sbgn
  /exporter/document/event/{identifier}.pdf
  /exporter/diagram/{identifier}.{ext}     (png, jpg, jpeg, svg, gif)
  /exporter/reaction/{identifier}.{ext}
  /exporter/fireworks/{species}.{ext}
  

  Probing anyway confirms it: /ContentService/exporter/event/R-HSA-5683177.biopax2,
  .biopax, and /ContentService/exporter/biopax/<id> all return 404, while .sbml
  returns 200. So SBML and SBGN are per-identifier; BioPAX is not.

  Reactome does still publish BioPAX, but only as bulk archives —
  https://reactome.org/download/current/biopax2.zip (Level 2, ~146 MB) and biopax.zip
  (Level 3, ~166 MB), both 200 today, containing every pathway per species. That is a very
  different shape from a per-id fetch and would mean caching or server-side extraction.

  So the realistic options are: wait for Reactome to repair the legacy exporter; pull BioPAX
  from PathwayCommons instead (which is where the search side already goes); build on the
  bulk archives; move the import to SBML/SBGN via ContentService and give up BioPAX-specific
  detail; or retire the feature. Worth a decision either way — the endpoint we use has been
  deprecated on Reactome's side for years.

  One thing that makes any ContentService route cheaper than it looks: they publish a
  machine-readable OpenAPI 3.0.1 spec at https://reactome.org/ContentService/v3/api-docs
  — 83 paths, 39 schemas, tagged by area (events, entities, pathways, participants, species,
  mapping, interactors, ...). If we go that way we can generate a typed client rather
  than hand-rolling URL/HttpURLConnection calls the way the current import does, using the
  same OpenAPI Generator v7.1.0 toolchain already wired up in tools/openapi-clients.sh for
  vcell-restclient / python-restclient / the Angular client. A generated client would also
  give us real status handling for free, which is the failure mode at the top of this issue.

Already done

CI is no longer blocked by this: PathwaySearchTest.pathwayDownloadTest now skips on a
non-XML 200 rather than failing the required CI-Test-group-Fast check (#2081, merged as
d4fc7b1ed7). That change is test-only and deliberately does not touch the client path —
this issue covers the user-facing half.

Note the two services are independent: PathwayCommons search works, so users can find
pathways and then fail to import them.