--- title: "FormAssembly Logs" description: "How to find out why a step failed — the per-workflow execution log, what each failure reason means, how long entries are kept, and where delivery results are recorded on a response." slug: "formassembly-logs" audience: "all" generated_at: "2026-10-16T20:50:24.371Z" screenshots: - "/docs/screenshots/formassembly-logs/workflow-errors.png" --- ## What the FormAssembly Execution log records The Execution log is a per-workflow diagnostic record of every step failure FormAssembly's workflow engine reported while running your workflow, plus every replay an author requested and every replacement an author made. It exists to answer one question: **why did this step fail?** Each failure entry carries the full error text the failing system returned — the third-party rejection, the email transport message — so you can fix the step or the connection without guessing. Replay entries are notices rather than failures ("Replayed from {step} by {user}") and carry no error text, and replacement entries ("Replaced on a corrected version at {step} by {user}") carry none either. The Execution log records two kinds of failure: - **Failures a step routed as a failure** — a third-party service rejecting a Connector step's request, an email transport error, or a step whose retry attempts ran out. Connector steps and Email steps are the step types that fail this way today. - **Failures that stop the run outright** — a step that cannot proceed on the run's own data and has no failure route that could change the outcome, such as a Redirect step whose URL does not resolve to a usable web address. The entry is recorded before the run ends, because the raw reason is exactly what you need to fix the step. The Execution log does **not** record: - Successful steps. The Execution log is a record of failures, replays and replacements, not an execution history of everything a run did. - Platform errors — a fault inside FormAssembly itself rather than in your workflow or a connected service. Those are reported to FormAssembly's own monitoring, not to your workflow, because no workflow can be authored around them. - The data FormAssembly sent to an external system, or how each field mapping resolved. **Only three step types record failure entries in the Execution log:** Connector steps, Email steps and Redirect steps. A collect (Form) step records nothing here, so an empty Execution log for a workflow built only of collect steps is expected. **One entry is recorded per failed attempt.** A step that retries and fails three times produces three entries, each with its own attempt number. Test runs record entries exactly as live runs do, and those entries are marked as test. ## How do I open the Execution log? The Execution log is scoped to a single workflow. You can reach it two ways: 1. From the **Workflows** list, open the row menu for the workflow and choose its execution log. 2. From the workflow builder toolbar, alongside the links to that workflow's responses and analytics. The page opens with the breadcrumb **Workflows / {workflow name} / Execution log**, and lists the workflow's failures with the most recent first. The builder link appears only once a workflow has been saved — an unsaved workflow has never run, so it has nothing to log. ![The Execution log page for a workflow, showing the Date range, Step type and Failure kind filters](/docs/screenshots/formassembly-logs/workflow-errors.png) ## What does each Execution log entry show? Every entry identifies the failure precisely enough to act on: - **The step** that failed, and its step type (Connector step, Email step, or Redirect step). - **The attempt number**, so a repeated failure reads as a sequence of attempts rather than as separate problems. - **The failure kind** — a short classification of what went wrong (see the table below). - **The time** the failure happened. - **The error text** the failing system returned, on a failure entry. Long messages are shortened and marked as truncated. - For Connector steps, **which operation failed** and its direction — inbound (reading data into the form) or outbound (sending data to the external system). The error text is treated as data that may contain respondent information. FormAssembly never writes it to its own application logs, and deletes it on the same triggers as respondent data: log retention, workflow or account deletion, and response purge. ## Do replays appear in the Execution log? Yes. When an author replays a response from a step — re-running the run from that point — FormAssembly records an entry in the Execution log reading "Replayed from {step} by {user}", so the replay sits in the list beside the failures it answers. A replay entry is not a failure: it carries no error text, it always shows attempt 0, and it names the person who requested it. Replay is not one of the options in the **Failure kind** filter, because it is not a failure kind. If the requesting user's account has since been deleted, the entry remains but shows no name. ## Do replacements appear in the Execution log? Yes. When an author replays a response onto a corrected version of the workflow — replacing the original response — FormAssembly records an entry reading "Replaced on a corrected version at {step} by {user}". One entry is recorded against the original response, naming the step the replacement started from and the person who made it. Like a replay entry, a replacement entry is not a failure: it carries no error text, and it is not one of the options in the **Failure kind** filter. ## How do I filter the Execution log? Three filters sit above the list, each defaulting to everything: 1. **Date range** — set a window instead of **All dates** to narrow to the period you are investigating. 2. **Step type** — set a step type instead of **All step types** to look at only **Connector step** failures, only **Email step** failures, or only **Redirect step** failures. 3. **Failure kind** — set a kind instead of **All kinds** to separate, for example, expired credentials from rate limiting. Combine all three when a workflow has failed in more than one way: filtering to one step type and one kind is usually the fastest route from "this workflow is failing" to "this connection needs reconnecting". ## Failure kinds The failure kind names the class of failure so you can act on it without reading the raw error text. The names below are exactly the options the **Failure kind** filter offers. | Failure kind | What it means and what to do | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | Authentication failed | The credentials for the connection have expired or been revoked. Click **Reconnect** on the connection from **Connections**. | | Permission denied | The connected account is signed in but lacks permission for what the step tried to do. Check the account's object and field access in the target system. | | Rate limited | The external service rejected the request because too many were sent. This often resolves on its own. | | Service unavailable | The external service was temporarily unavailable. This often resolves on its own. | | Transport error | The request could not be completed, or the error did not fit another kind. The raw error text is the detail to read here. | | Wrong connection for connector | The connection chosen on the step cannot back that connector. This is a configuration fault rather than a credential one — change or remove the connection on the step. | | Retries exhausted | A step that was set aside to be retried ran out of attempts. Such an entry names no operation, because the retry decision is made before the work runs. | | Redirect URL invalid | A Redirect step's URL resolved to something that is not a usable absolute web address. Because the URL depends on respondent data, this can only be caught at run time — check how the redirect URL is built. | | Email field invalid | An Email step's recipient address did not pass its check when the step ran. The step fails as a whole rather than sending to the good addresses and dropping the bad one — check the step and the field it takes the address from. | | Email too large | An Email step's message, attachments included, would exceed the size limit. The check runs before the send, so nothing was delivered — reduce or remove attachments on the step. | New step types and new failure sources may add kinds over time, so treat the list above as the current set rather than a closed one. ## Where else do step failures appear? The Execution log is the most complete view, but failures surface in three other places in FormAssembly: **On the Responses list.** A red warning triangle beside the status badge, labelled "A delivery for this response failed", marks a response where something never reached its destination. The triangle is shown whatever the response's own status says: a response can read **Completed** and still have a failed delivery behind it, and an in-progress response can already have one. Open **Responses** for the workflow, then use the search box, **Filters** and the **Timeframe** control to find affected responses. **On a response's detail page.** Open a response with **View response** from the row or the row's **Response actions** menu. The detail page lists the delivery records for that response and, after them, the Execution log entries recorded for that response — most recent first, each with step, step type, attempt, kind, time and the full error text, plus a link to the full log for the workflow. A failed delivery record shows a short reason naming the kind and a **See error details** link down to its full error text. That link is best-effort: delivery records live as long as the response, while Execution log entries expire after 90 days, so an older response may show the short reason with no link. **By email.** Owner failure emails are a workflow setting: turn on **Email the owner when a step fails** under **Properties → Notifications** in the builder. The setting is **off by default**, so a workflow that has never been changed emails no one. With it on, FormAssembly emails the workflow owner with the workflow name, the step name, a human-readable reason and a count of failures since the last notification. The setting covers Connector steps, Email steps and Document generation steps, as well as a response stopped by an error. Fai or the API can override it for a single failure route — turning notification on for one route in a workflow that is otherwise off, or off for one route in a workflow that is otherwise on. Notifications are debounced per workflow so a burst of failures does not flood your inbox: after an email is sent, further failures are counted quietly for about an hour and reported in the next email. If failures stop entirely during that quiet period, no catch-up email is sent — the initial email already told you something was wrong, and the Execution log holds the full detail. **Test and preview runs never send the owner notification email.** A test run records Execution log entries exactly as a live run does — entries yes, email no — so a failure you triggered while testing appears on this page but produces no message in your inbox. Two other situations also produce no email: **Email the owner when a step fails** is off (the default, or an override that turns it off for that route), and the workflow owner has no reachable email address. If you turned on owner notification and tested it, check the Execution log to confirm the failure was recorded, then verify with a live response before assuming notification is broken. ## Can I ask Fai about a failure? Yes. Click **Open Fai** and ask why a step or a response failed. Fai, FormAssembly's built-in AI assistant, can read the Execution log entries for a workflow or a single response and report the failure reason back to you in the chat, which is often quicker than filtering the list by hand. Fai sees only what you can see — the same workflows and responses your own account has access to. ## How long are Execution log entries kept? Execution log entries are deleted **90 days** after they are recorded. Deletion runs daily and touches nothing else — delivery records and audit records have their own retention. Entries are also deleted early when the data they describe goes away: deleting a workflow or an account removes its Execution log entries, and purging a response removes the entries recorded for that response. Because the Execution log expires at 90 days while responses keep their delivery records, an older response can show that a delivery failed without showing the original error text. Investigate failures while they are recent. ## Who can see the Execution log? Access follows workflow access. The workflow's author reads the Execution log for the workflows they own, a collaborator reads it for the workflows shared with them, and an account administrator reads the account's entries. No one can read another account's entries. Entries are never editable or deletable by hand — FormAssembly writes them during execution, and retention removes them. ## Audit Trail: who did what The Execution log answers *why a step failed*. A separate record, the **Audit Trail**, answers *who did what* for compliance activity — the compliance events recorded against your workflows and policies, such as evaluations, reviewer decisions and policy changes. Open it from **Compliance** in the left navigation. The Audit Trail requires the Enterprise plan. The Audit Trail is append-only, it can be narrowed with free-text search, a **Source** filter and a date range, and it can be exported to CSV. It deliberately carries **no error text**, which is why the Execution log exists alongside it. See also: the Audit Trail documentation for the full list of recorded events. ## Tips & Troubleshooting - **A failure appears in the Execution log but the response looks fine.** That is expected. A delivery failure does not change a response's own status — FormAssembly records the response as completed when the run reaches its end, whether or not a connector or email reached its destination. Use the warning triangle on the Responses list, not the status badge, to find undelivered responses. - **Three entries for one failure.** A step that retries records one entry per attempt. Read the attempt numbers: the last attempt usually carries the real kind, and a **Retries exhausted** entry means the attempts ran out. - **The same failure over and over across many responses.** Filter by **Failure kind** first. **Authentication failed** across every response almost always means one expired connection, not a broken workflow — click **Reconnect** on it from **Connections**. **Wrong connection for connector** means the step is pointing at a connection that cannot serve it, so reconnecting will not help — change the connection on the step. - **An entry with no matching response.** The Execution log is the only surface that shows failures from runs that never got far enough to be saved as a response — for example a Connector step that pre-fills a form and fails before anyone submits it. There is no response to open; the Execution log entry is the whole record. - **Nothing in the Execution log, but a step still isn't working.** Check that your filters are not hiding it (set **Date range** back to **All dates**, **Step type** to **All step types**, and **Failure kind** to **All kinds**). If the list is genuinely empty, the step may be succeeding while doing nothing you expected — check the response detail page's delivery records and the path the run took. Remember that collect steps never record Execution log entries. - **Test runs count.** Entries from test and preview runs are recorded and marked as test, so a log full of failures after a testing session is normal. Re-check after a live run before assuming the workflow is broken. - **No failure email arrived.** The usual reason is that **Email the owner when a step fails** under **Properties → Notifications** is off, which is the default. Turn it on, then confirm with a live response — a test or preview run records Execution log entries but never sends the owner notification email. - **The Execution log does not replay failures.** There is no re-run control on this page — a replay is started from the response's own detail page, and the Execution log records it once it has happened. For a configuration problem, fix the connection, credentials or step configuration, then republish and collect a new response.