apache/beam · warning

Error search FHIR resources writing to Dead Letter Queue.

Error message

Error search FHIR resources writing to Dead Letter Queue.

What it means

FhirIO.Search's processElement executes a FHIR search per (store, parameters) pair. If the search parameters are invalid (IllegalArgumentException) or no results exist where the code requires one (NoSuchElementException), the searchResourcesErrorCount metric is incremented, this warning logged, and the input parameters are emitted to FhirIO.Search.DEAD_LETTER as a HealthcareIOError so the pipeline keeps running.

Solutions

1. Read the DEAD_LETTER HealthcareIOError to see which parameters and exception caused the failure.
2. Validate resource type names against the FHIR spec and confirm search parameter keys are supported for that type.
3. Handle empty result sets explicitly in your parameters/queries before calling search.
4. Check fhirStore path format and store configuration in the Healthcare API.

Example fix

// before
input.apply(FhirIO.search())  // with parameters map containing unsupported key
// after
// validate parameters first
Map<String, DiscreteValue> validated = validateSearchKeys(resourceType, params);
validated.apply(FhirIO.search());

// Java: sanity-check search parameters before FhirIO.search()
if (resourceType == null || resourceType.isBlank() || !FHIR_RESOURCE_TYPES.contains(resourceType)) {
  throw new IllegalArgumentException("Unsupported FHIR resource type: " + resourceType);
}
for (String key : parameters.keySet()) {
  if (!SUPPORTED_SEARCH_KEYS.getOrDefault(resourceType, Set.of()).contains(key)) {
    throw new IllegalArgumentException("Unsupported search key " + key + " for " + resourceType);
  }
}

When it happens

Trigger: Passing an invalid resource type or malformed query parameter map to FhirIO.search(); a search returning an empty bundle where the code unconditionally reads the first entry (NoSuchElementException); bad fhirStore strings.

Common situations: Typo'd search parameters (e.g. unsupported search key for the resource type); searching a resource type not configured in the store; queries with invalid date/value syntax; pagination edge cases producing empty pages.

Understand the failure class

Background: "Invalid query parameter" / "Failed to parse value of ...": fixing bad query string parameters across APIs — this error's family across 36 libraries.

Related errors

• Error executing GetPatientEverything: FHIR resources…
• Error fetching Fhir resource with ID
• Failed to parse payload
• Error fetching HL7v2 message with ID
• error occurred while performing search for query

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

Appendix: source

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

      }

      /**
       * Process element.
       *
       * @param context the context
       */
      @ProcessElement
      public void processElement(ProcessContext context) {
        FhirSearchParameter<T> fhirSearchParameters = context.element();
        try {
          context.output(
              KV.of(
                  fhirSearchParameters.getKey(),
                  searchResources(
                      fhirSearchParameters.getResourceType(), fhirSearchParameters.getQueries())));
        } catch (IllegalArgumentException | NoSuchElementException e) {
          searchResourcesErrorCount.inc();
          log.warn("Error search FHIR resources writing to Dead Letter Queue.", e);
          context.output(
              FhirIO.Search.DEAD_LETTER, HealthcareIOError.of(fhirSearchParameters.toString(), e));
        }
      }

      private JsonArray searchResources(String resourceType, @Nullable Map<String, T> parameters)
          throws NoSuchElementException {
        long start = Instant.now().toEpochMilli();

        HashMap<String, Object> parameterObjects = new HashMap<>();
        if (parameters != null) {
          parameters.forEach(parameterObjects::put);
        }
        FhirResourcePagesIterator iter =
            FhirResourcePagesIterator.ofSearch(
                client, fhirStore.toString(), resourceType, parameterObjects);
        JsonArray result = new JsonArray();
        while (iter.hasNext()) {

View on GitHub (pinned to 12126d8942)