Enrich docling-serve error messages with workaround hints (#37)

When a docling-serve response contains a known failure pattern, append
a short actionable hint to the message before it surfaces in the
plugin's toast. Today: one pattern, the Apple-Silicon MPS + float64
RT-DETRv2 bug. Tomorrow: easy to add more patterns to the same table.

A real user hit "HTTP 500: Cannot convert a MPS Tensor to float64 dtype
…" with no recovery path from the toast itself. With this change the
toast also says: "Apple Silicon MPS bug — restart docling-serve with
PYTORCH_ENABLE_MPS_FALLBACK=1 (see README → Troubleshooting)." The
README change in the previous PR (docs/troubleshooting-mps) owns the
long-form explanation; this PR is just the in-app pointer.

Design

- New `src/utils/serverErrorHints.ts` exports a `KNOWN_SERVER_ISSUES`
  table (`{id, matches, hint}[]`) and a pure `enrichServerError(message)`
  helper. The helper appends one hint per matching entry, separated by
  " · ". No match → unchanged message. Predicate throws are swallowed —
  a broken pattern must never break error surfacing.

- The MPS pattern matches both "MPS" and "float64" as independent tokens
  rather than as a fixed phrase, so it survives reorderings across
  docling / transformers / PyTorch versions.

- Wired into convert.ts at the two outbound-error sites:
    * parseConvertResponse — non-2xx with body.
    * convertAttachmentInner — server-side "failure"/"partial_success".
  Both apply the helper just before returning the message that becomes
  the toast.

Tests

- New `test/serverErrorHints.test.ts` follows the Goldberg conventions
  already in place (3-part names, AAA blocks, BDD assertions, `#cold`
  tag, realistic input verbatim from a docling-serve traceback).
- Covers: MPS+float64 match (both orderings), unrelated errors pass
  through unchanged, empty input, single-token false-positive cases
  (MPS without float64, float64 without MPS — neither triggers).
- Sanity-checks the table itself (every entry has id/matches/hint;
  ids are unique).

`npx tsc --noEmit`, `npx eslint .`, `npx prettier --check .`, and
`npm run build` all pass.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: brianckeegan

src/modules/convert.ts

@@ -17,6 +17,7 @@ import {
   stripExistingFrontmatter,
 } from "../utils/frontmatter";
 import { withDbLock } from "../utils/dbLock";
+import { enrichServerError } from "../utils/serverErrorHints";
 import { toast } from "./ui";
 
 const LOG = "[zotero-docling]";
@@ -369,7 +370,8 @@ async function parseConvertResponse(r: Response): Promise<FetchOutcome> {
   if (!r.ok) {
     const errs = formatServerErrors(data);
     const hasDetail = errs && !errs.startsWith("status=");
-    return { ok: false, message: hasDetail ? `${label}: ${errs}` : label };
+    const raw = hasDetail ? `${label}: ${errs}` : label;
+    return { ok: false, message: enrichServerError(raw) };
   }
   return { ok: true, data };
 }
@@ -653,9 +655,10 @@ async function convertAttachmentInner(
   const okStatus =
     data.status === "success" || data.status === "partial_success";
   if (!okStatus) {
+    const raw = `Conversion ${data.status ?? "unknown"}: ${formatServerErrors(data)}`;
     return {
       status: "error",
-      message: `Conversion ${data.status ?? "unknown"}: ${formatServerErrors(data)}`,
+      message: enrichServerError(raw),
     };
   }
   const rawMarkdown = data.document?.md_content;

src/utils/serverErrorHints.ts

@@ -0,0 +1,70 @@
+// Recognise known shapes of docling-serve / Docling / upstream-library
+// failure modes in raw error strings, and append a one-line actionable
+// hint to the message.
+//
+// Why this exists: the plugin's failure toast historically surfaces the
+// server's verbatim error ("HTTP 500: Cannot convert a MPS Tensor to
+// float64 dtype…"). For known patterns we can do better — append a
+// short hint pointing at the workaround, so the user doesn't have to
+// search the README to recover. The README still owns the long-form
+// explanation; this module just points there.
+//
+// Patterns are evaluated in order. Each matching pattern appends its
+// hint once. The function is pure and lives outside convert.ts so it
+// can be unit-tested without the Zotero global.
+
+interface KnownIssue {
+  /** Short identifier — surfaced in Zotero.debug logs but not the toast. */
+  id: string;
+  /**
+   * Predicate. A RegExp is cheapest; for multi-token AND-matching where
+   * order varies, prefer a function (see the MPS entry below).
+   */
+  matches: (message: string) => boolean;
+  /** One-line hint appended after a separator. Keep this short. */
+  hint: string;
+}
+
+// Order matters only insofar as a single match emits a single hint; if a
+// caller ever wants multiple hints from one message, they'll accumulate
+// in the order declared here.
+export const KNOWN_SERVER_ISSUES: ReadonlyArray<KnownIssue> = [
+  {
+    id: "mps-float64",
+    // RT-DETRv2 in transformers hard-codes a float64 tensor; PyTorch's
+    // MPS backend can't represent float64 on Apple Silicon. The two
+    // tokens can appear in either order across versions, so match each
+    // independently rather than as a fixed phrase.
+    matches: (m) => /\bMPS\b/.test(m) && /\bfloat64\b/i.test(m),
+    hint: "Apple Silicon MPS bug — restart docling-serve with PYTORCH_ENABLE_MPS_FALLBACK=1 (see README → Troubleshooting).",
+  },
+];
+
+/**
+ * Append known-issue hint(s) to a server error message. If no pattern
+ * matches, returns the message unchanged. Multiple matching patterns
+ * each append their hint, separated by " · ".
+ *
+ * Examples:
+ *
+ *   enrichServerError("HTTP 500: Cannot convert a MPS Tensor to float64 dtype")
+ *     → "HTTP 500: Cannot convert a MPS Tensor to float64 dtype
+ *        · Apple Silicon MPS bug — restart docling-serve with
+ *          PYTORCH_ENABLE_MPS_FALLBACK=1 (see README → Troubleshooting)."
+ *
+ *   enrichServerError("Server not reachable")
+ *     → "Server not reachable"   (unchanged — no known issue matched)
+ */
+export function enrichServerError(message: string): string {
+  if (!message) return message;
+  const hints: string[] = [];
+  for (const issue of KNOWN_SERVER_ISSUES) {
+    try {
+      if (issue.matches(message)) hints.push(issue.hint);
+    } catch {
+      // A broken predicate must never break error surfacing.
+    }
+  }
+  if (hints.length === 0) return message;
+  return `${message}\n· ${hints.join("\n· ")}`;
+}