Run logs explained: how to debug any Flowpath agent in under 5 minutes

Debugging a broken automation used to mean digging through email notifications, checking third-party dashboards, and manually tracing data through a chain of tools you don't fully control. With Flowpath's run logs, debugging a broken agent typically takes under five minutes, because every piece of information you need is in one place, organized exactly the way you need it.

This guide covers the run log structure, the most common failure patterns and how to diagnose each one, the filtering and search tools for tracking down intermittent issues, and a set of advanced techniques for proactive monitoring rather than reactive debugging.

The run log structure

Every execution of a Flowpath agent produces a run record. The run record has a header — showing the agent name, trigger type, start time, total duration, status and a unique run ID — followed by a sequential list of step records.

Each step record contains four sections. Input data shows exactly what data the step received from the previous step or the trigger — every field, every value, including null fields. Output data shows exactly what the step produced — again, every field. Execution time shows how long the step took to complete, in milliseconds. And status shows whether the step succeeded, failed, was skipped (because a branch condition wasn't met) or is currently running.

This structure means you can trace any piece of data through its entire journey through your workflow. If a HubSpot contact ends up with the wrong value in a field, you can open the run log and see exactly what value entered each step and what value exited it, until you find the point where the transformation went wrong.

The most common failure: missing required field

This accounts for roughly 45% of the agent failures we see across the Flowpath platform. The pattern is always the same: a downstream step expects a field that an earlier step didn't produce, usually because the data wasn't present in the trigger payload or enrichment returned null.

The run log will highlight the failing step in red and show an error message that typically reads something like: "Required field 'company_name' is null or missing." The fix is almost always one of three things: add a data transformation step to provide a default value when the field is null, add a branch condition before the failing step that routes null-field records to a fallback path, or update the enrichment step's field mapping to ensure the field is always populated.

The second most common failure: AI step output format mismatch

When an AI step returns something your downstream step can't parse — "Score: 74" instead of "74", or a JSON object with different key names than expected — the next step fails with a field mapping error. The run log will show you exactly what the AI step returned in the output data section. Nine times out of ten, the fix is a more explicit output instruction in the prompt.

Tracking intermittent failures

The failures that happen on 2% of runs are the hardest to debug because you can't reliably reproduce them. Flowpath's log filtering tools are designed specifically for this case.

Filter by status:error to see all failed runs in your selected time window. Filter by step_name to isolate failures at a specific step. Use the search bar to find runs where a specific value was present — for example, searching for "auth_error" in the output data field will find every run where a downstream API returned an authentication error, even if the step was marked as a warning rather than a failure.

Once you've found the failing run, compare its input data to a successful run for the same step. The difference between the two inputs is almost always the root cause of the failure.

Proactive monitoring with error alerts

Rather than checking logs reactively after a failure, set up error alert webhooks for your critical workflows. In the agent settings panel, you can configure a webhook URL that receives a POST request every time a run fails, including the full run ID, the failing step name and the error message.

Connect this webhook to a Slack notification using — appropriately — a Flowpath agent, and you'll be notified within seconds of any failure in a business-critical workflow. Combine this with the retry functionality (available on Growth and Enterprise plans) and most transient failures will auto-resolve before you even see the notification.