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.

Folio Log is always on

Whenever an error is raised anywhere inside the Folio package — including invocable Apex actions, triggers, and editor backend calls — Folio writes a record to the Folio Log object automatically. You don’t have to wire anything up to get this; it’s the package’s built-in error trail. The rest of this page is about how to understand and customize error handling on top of that baseline so you can shape it to your org’s requirements (notifications, retries, fault routing, etc.). Folio Log will always be there to review when something goes wrong, and it’s the first place to point the Folio Support team when you open a ticket. See the data model reference for the key fields and Configure Advanced Settings for retention.

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–public-group ID was passed to Share Document	Use only Public Group IDs
”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 = errorMessage and 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 both the Folio User and Folio Docs User permission sets — invocable Apex is only available to users assigned both.
Verify any referenced groups are 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__c flag on the parent record).
Transfer Document to Owner is idempotent in that re-running with the same newOwnerId is a no-op.

What is Folio?