apache/beam · error · IOException

Invalid DICOM web path

Error message

Invalid DICOM web path

What it means

WebPathParser.parseDicomWebpath splits a DICOM web URL on the literal delimiter '/dicomWeb/' and requires exactly two segments; otherwise it throws IOException('Invalid DICOM web path'). The input is not a recognizable Google Healthcare DICOMweb URL.

Source

Thrown at sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/healthcare/WebPathParser.java:40

@SuppressWarnings({"StringSplitter"})
public class WebPathParser {

  public static class DicomWebPath {
    public String studyId = "";
    public String seriesId = "";
    public String instanceId = "";
    public String dicomStorePath = "";
    public String project = "";
    public String location = "";
    public String dataset = "";
    public String storeId = "";
  }

  public DicomWebPath parseDicomWebpath(String unparsedWebpath) throws IOException {
    String[] webPathSplit = unparsedWebpath.split("/dicomWeb/");

    if (webPathSplit.length != 2) {
      throw new IOException("Invalid DICOM web path");
    }

    DicomWebPath dicomWebPath = new DicomWebPath();

    dicomWebPath.dicomStorePath = webPathSplit[0];
    String[] storePathElements = dicomWebPath.dicomStorePath.split("/");
    dicomWebPath.project = storePathElements[1];
    dicomWebPath.location = storePathElements[3];
    dicomWebPath.dataset = storePathElements[5];
    dicomWebPath.storeId = storePathElements[7];

    String[] searchParameters;
    searchParameters = webPathSplit[1].split("/");
    if (searchParameters.length < 2) {
      throw new IOException("Invalid DICOM web path");
    }
    dicomWebPath.studyId = searchParameters[1];
    dicomWebPath.seriesId = searchParameters[3];

View on GitHub (pinned to 12126d8942)

Solutions

1. Ensure the path contains the literal segment '/dicomWeb/' exactly once, e.g. projects/p/locations/l/datasets/d/dicomStores/s/dicomWeb/studies/123/series/456/instances/789
2. Trim and normalize the URL before parsing
3. Check for URL-encoding of the slashes and decode first
4. Verify you are not passing only the store path when a full study/series/instance URL is required

Example fix

// before
parser.parseDicomWebpath("projects/p/locations/l/datasets/d/dicomStores/store/studies/1.2/series/3.4/instances/5.6");
// after
parser.parseDicomWebpath("projects/p/locations/l/datasets/d/dicomStores/store/dicomWeb/studies/1.2/series/3.4/instances/5.6");

java
static boolean isValidDicomWebPath(String url) {
  return url != null && url.split("/dicomWeb/").length == 2;
}
if (!isValidDicomWebPath(unparsedWebpath)) {
  throw new IllegalArgumentException("URL must contain exactly one '/dicomWeb/' segment");
}

java
try {
  DicomWebPath p = parser.parseDicomWebpath(url);
} catch (IOException e) {
  if ("Invalid DICOM web path".equals(e.getMessage())) {
    throw new IllegalArgumentException("Not a DICOMweb URL: " + url, e);
  }
  throw e;
}

When it happens

Trigger: Calling parseDicomWebpath (via parsedDicomWebPath/dicomWebPath in DicomIO) with a URL that lacks '/dicomWeb/', contains it multiple times, or has different casing/spacing.

Common situations: Passing a plain DICOM store path (projects/.../dicomStores/store) without the /dicomWeb/ suffix; passing an AWS/orthanc DICOMweb URL; double-encoding the URL so '%2FdicomWeb%2F' isn't matched; trailing whitespace.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• The PCollection tuple must have the DicomIO.ReadStudyMetadat
• The PCollection tuple must have the FhirIOPatientEverything.
• The PCollection tuple must have the HL7v2IO.Read.OUT and HL7
• The PCollection tuple must have the HL7v2IO.HL7v2Read.OUT an
• GET request for %s returned null

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/59bb7468aa6742ee. Report an issue: GitHub.