Handle Invocable Apex Errors
Most failures in Folio invocable actions fall into a small number of categories. Build a Fault Path off every action and route to a logger or admin-notification step. The sections below cover the failure categories you’ll see, the fault-path pattern, a debugging checklist, and which actions are safe to retry.
For the per-action reference, see Automate with Invocable Apex. For chaining recipes and end-to-end scenarios, see Review Invocable Apex Use Cases.
Common failure categories
| Failure | Likely cause | Fix |
|---|---|---|
errorMessage mentions invalid IDs | ID values point to deleted/missing records | Validate inputs upstream; trim empty/null IDs |
| ”User does not have access” / “no rows” | Running user lacks sharing or FLS to the targeted Documents | Confirm the running user has Folio permissions and Document access |
| ”User is inactive” / “missing permission set” | Share or transfer target is inactive or lacks Folio permission | Check user activation status and Folio permission set assignment |
| ”Group is not a public group” | A non-Regular group ID was passed to Share Document | Use only public groups of type Regular |
| ”Object not linkable” | Record ID for an object not on the Linkable Object Allowlist | Add the object in Configure the Admin Panel → Linkable Objects |
| ”Template / source mismatch” | Source record’s object type doesn’t match the template’s configured Source Object | Confirm template configuration; route the wrong-object branch upstream |
| Empty result, no error | All filters were empty or the running user has no access to matching Documents | Always supply at least one filter; consider byOwnerIds or byParentRecordIds |
Fault path design
For every invocable action that returns success/errorMessage:
- Add a Fault Path out of the action.
- On the fault path, set a flow variable like
flow_error_message = errorMessageand persist it (custom log object, platform event, email alert). - End the flow on a controlled error path, not a hard failure. This avoids confusing the running user with raw Apex errors.
For Apply New Owner Sharing, which does not return an output payload, design idempotent retries (e.g., schedule a follow-up flow to confirm sharing landed) rather than expecting an explicit success signal.
Admin debugging checklist
When a flow misbehaves:
- Re-run the flow in Debug mode in Flow Builder, capturing inputs and outputs.
- Check the Folio Logs retention horizon (see Configure Advanced Settings).
- Confirm the running user has the Folio User permission set (and Folio Docs User if the action touches Docs-only features).
- Verify any referenced groups are Regular public groups.
- For Link Documents to Records, confirm the target object is on the Linkable Object Allowlist.
- For Create Document from Template, confirm template / Source Object compatibility.
Idempotency and retries
- Apply Tag, Link Documents to Records, Share Document (additive), and Apply New Owner Sharing are safe to rerun — Folio de-dupes existing Tag links, Junctions, and shares.
- Clone Document and Create Document from Template are not idempotent — every call creates new Documents. Guard against re-firing flow paths using a Decision node (e.g., a
Has_Handoff_Doc__cflag on the parent record). - Transfer Document to Owner is idempotent in that re-running with the same
newOwnerIdis a no-op.
Related: Automate with Invocable Apex · Review Invocable Apex Use Cases · Configure Advanced Settings