#15605·activepieces

[Feature]: Expose a failed step's error as structured fields, not a serialized JSON string

Author: majewskibartoszCreated Sep 17, 2026Updated Sep 17, 2026
Labels🌟 feature🔄 area/flows🛟 support💫 priority

Ask

Let a later step read a failed step's error as fields, so a flow can forward an integration's exact error to its own users without a code step.

Today {{step_N['error']}} resolves to { message: <string> } where the string is the serialized FriendlyPieceError. Reaching status, responseBody or the API's own message means "Continue on failure", a code step, JSON.parse, a .message hop, and stripping an Error: prefix that only exists on some deployments.

Ref: Pylon 6022 (paid, priority account). Same ask as activepieces/activepieces#9519 (Oct 2025, canceled without a repro).

Proposed

In packages/server/engine/src/lib/handler/context/flow-execution-context.tsgetStepView — parse the stored string with tryParseFriendlyPieceError and expose named fields alongside the existing message:

  • apiMessage — what the API returned, the "exact error message a piece has"
  • status
  • responseBody
  • errorName

message stays as-is, so nothing existing flows read changes. Pick fields explicitly, never spread the parsed object (two of its fields must not reach flow data, tracked internally).

Follow-up, separate decision: flip message to the plain text behind a deprecation window and a breaking-changes entry.

Evidence

Reproduced live on a full local stack at HEAD identical to the current cloud deploy, both execution modes. For piece errors the structured fields are already populated in the stored payload; they are only unreachable from expressions.

Out of scope

The Error: prefix varying by AP_EXECUTION_MODE is a defect, filed separately.

Source: activepieces/activepieces