aws / aws/aws-durable-execution-docs

docs: add error-handling example for BatchResult on Map operations page

Open
#159 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
13
Forks
13
Avg merge
3d 2h
Merged PRs (30d)
25

Description

## Problem

When using `context.map()` with `CompletionConfig.all_successful()`, if all map items throw exceptions, `get_results()` returns an empty list with no indication of what went wrong. Users who are not already aware of `BatchResult.get_errors()` and `BatchResult.failed()` tend to fall back to wrapping their map function body in `try/except` and returning a result dict so they can inspect failures — even though the SDK already exposes a proper API for this.

The root cause appears to be discoverability: the error-inspection methods exist and are reference-documented, but nothing on the map operation page nudges users toward them.

## Current docs state

The [Map operations reference](https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/map/#result-types) does document the following on `BatchResult`:

- `get_results()`
- `get_errors()`
- `succeeded()`
- `failed()`
- `throw_if_error()`

However:

- The **introductory example** at the top of the page only shows `result.getResults()` / `result.to_dict()` — the success path.
- There is **no error-handling example** on the map page itself.
- There is no guidance on how to combine `CompletionConfig` with partial success/failure inspection.

As a result, users reading the page top-down can easily walk away thinking the only way to see per-item failures is to catch exceptions inside the map function.

## Suggested improvement

1. **Add an "Error handling" section** on the Map operations page, positioned immediately after the basic example. It should include:
- A short explanation that `BatchResult` exposes both the successful and failed items, and that catching exceptions inside the map function is not required to inspect failures.
- A runnable code sample using `CompletionConfig` (e.g. `all_successful()` and at least one more permissive variant) that demonstrates iterating over `get_errors()` and `failed()` to inspect partial success/failure.
- A note on when `get_results()` returns an empty list vs. raises, so the empty-list case does not surprise users.

2. **Add a "Common patterns" subsection** to the map page covering:
- Inspecting partial failures without raising.
- Re-raising selectively after inspection (via `throw_if_error()` or manual logic).
- Choosing between `CompletionConfig` modes based on the desired failure semantics.

3. **Cross-link** from the introductory example to the new "Error handling" section so users scanning the page see the pointer before they write their own `try/except` workaround.

## Severity

Low — the API exists and works; this is a documentation discoverability gap, not a functional one.

## Affected docs

- [Map operations reference — Result types](https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/map/#result-types)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.