fabric-error-handling

Error handling convention (Fabric notebooks)

Two tiers. Pick the right one per block of code; don't mix them inside a single logical operation.

Tier 1 — Setup / preconditions (hard fail)

Raise immediately. No try/except wrapping, no "best effort" semantics. Applies to:

• Auth: token acquisition, Key Vault secret fetches, connection-string pulls
• Required-config validation: missing required variables, unset placeholders that would produce invalid requests
• Target resolution where the target is a single item: resolve a workspace ID, resolve an item ID, lookup the Variable Library GUID

Tier 1 functions surface the cause in the exception message (HTTP status, what was missing, what was searched). They never swallow errors to keep the notebook running — if a precondition fails, subsequent cells will produce misleading output or worse, silent data corruption.

Tier 2 — Bulk operations (soft fail)

Track per-item results, continue the loop, print a summary at the end. Applies to:

• Per-table maintenance (OPTIMIZE, VACUUM, TBLPROPERTIES alterations)
• Per-item enumeration (list all items, extract GUIDs, update a set of value sets)
• Per-workspace iteration

Canonical result shape — use this exact structure in every Tier 2 notebook:

results = {
    "succeeded": [],   # list[str] of item names
    "skipped":   [],   # list[dict]: {"name": str, "reason": str}
    "failed":    [],   # list[dict]: {"name": str, "error": str}
}

Append into succeeded / skipped / failed inside the loop, never halt the loop on a single failure, then print a summary block at the end:

── Summary ───────────────────────────────────
  Succeeded: 47
  Skipped:    2
  Failed:     1
    - `dbo`.`TransactionLine`: snapshot conflict (24556) — retry

STRICT flag

Every Tier 2 notebook exposes a top-level boolean in its config cell:

# False (default) — print the summary and continue even if some items failed.
#                   Right for scheduled runs: one bad item shouldn't stop the
#                   rest of the work, and the per-item report is enough signal.
# True  — raise RuntimeError after the summary when any item failed. Use from
#         CI / orchestration where you want the notebook exit code to reflect state.
STRICT = False