Skip to content

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

fix(flows): stop template imports from failing when the v23 upgrade has no stored flow (#15736)

Othman Abu Ajamieh342df56ae200
diff --git a/brain/knowledge/flows-execution/flows.md b/brain/knowledge/flows-execution/flows.md
index ea6732d5baf..cb6dbc914e6 100644
--- a/brain/knowledge/flows-execution/flows.md
+++ b/brain/knowledge/flows-execution/flows.md
@@ -8,7 +8,7 @@ Flows are the core automation primitive: a versioned directed graph of trigger +
### Entities & services
- **Flow** — persistent record: status (ENABLED/DISABLED), folderId, publishedVersionId, externalId, operationStatus (NONE/DELETING/ENABLING/DISABLING), ownerId, createdBy (`FlowCreator`: `{type: MCP|AGENT, id}`, null for humans → "AI" badge).
-- **FlowVersion** — immutable-once-LOCKED snapshot of the graph. DRAFT is editable; current schemaVersion is `'22'`. Holds trigger (full graph JSONB), connectionIds, agentIds, notes.
+- **FlowVersion** — immutable-once-LOCKED snapshot of the graph. DRAFT is editable; current schemaVersion is `'27'` (`LATEST_FLOW_SCHEMA_VERSION`). Holds trigger (full graph JSONB), connectionIds, agentIds, notes.
- **Folder** — simple per-project grouping, case-insensitive unique.
- Core service: `flow.service.ts`; single controller endpoint `POST /v1/flows/:id`.
@@ -24,6 +24,7 @@ Flows are the core automation primitive: a versioned directed graph of trigger +
- **A CODE step's compiled size is its `packageJson`, not its code — bundling *inlines* `node_modules`, it does not exclude it.** This gets assumed backwards a lot: there is no `node_modules` at runtime precisely *because* esbuild inlines every dependency into the step's `index.js`. Measured on cloud, Aug 2026: a step with **1,870 characters** of user source and `{"pdfkit":"0.14.0","aws-sdk":"2.1531.0","uuid":"9.0.1"}` compiles to **24.13 MB**, of which 24.13 MB is `node_modules` — **21.16 MB of it `aws-sdk` alone**. v2 of that SDK resolves its ~200 service clients by dynamic `require`, so esbuild cannot tree-shake it and inlines all of them; `@aws-sdk/client-*` (v3) would be a few hundred KB. Fleet-wide there were 13,918 compiled steps totalling 1.4 GB, **61 of them over 10 MB**, and per *flow* the totals reach **190.7 MB across 40 code steps**. That per-flow number is the one that matters operationally, because `flowBundleStore.publish` holds a flow's entire compiled output in memory at once (three copies — see the OOM gotcha on [[workers]]). To find the offenders: esbuild leaves `// node_modules/<pkg>/…` markers in the output, so you can attribute bytes per package by summing the lines between markers.
- **Step output nesting (schema v21+)**: every step output is wrapped as `{ output, error? }`; expressions must use the `['output']` accessor. The v20→v21 migration rewrites existing expressions via `expression-rewriter`.
- **Migrations run on every single-version read, including the worker's own `getFlowVersion`** (`findOne` → `flowVersionMigrationService.migrate`). So no run can execute an unmigrated version, and restoring an old version migrates it forward too. The listing path is the exception: `flowVersionService.list()` paginates the repository directly and hands back whatever schema version the row holds, so a caller reading the version history can see unmigrated rows. The result is persisted, then short-circuits at `LATEST_FLOW_SCHEMA_VERSION`. The old version is saved to `backupFiles[oldSchemaVersion]` first — **that** is what a restore reads, so there's no need to keep an old code path alive "just in case". Nothing restores on its own: `flowVersionBackupService.get()` has no callers, so recovering a version is a deliberate manual step. A migration that throws pages on-call (`FLOW_MIGRATION_FAILED`).
+- **Template migrations run on a flow version that is not stored.** `migrateFlowVersionTemplate` (the `IMPORT_FLOW` pre-validation and the template controllers) builds a stand-in version with `flowId: ''` and passes no `MigrationContext`, so there is no project or platform either. A migration that looks anything up by flow id must treat "not found" as "nothing stored", never throw: the v23 piece-upgrade audit event used `findOneByOrFail`, which turned every import of an old template holding a register-listed piece into a 500 (the event-destinations "Generate handler flow" hit it with webhook `0.1.33`).
- **Continue on Failure**: CODE/PIECE steps with `continueOnFailure.value: true` carry `onSuccess`/`onFailure` sub-trees under `settings.errorHandlingOptions.continueOnFailureBranches`.
- **`addActionUtils.clone()` is the single chokepoint for renaming copied steps and rewriting their `{{ }}` references** — paste, duplicate step, and duplicate branch all route through it. It walks the **whole `settings`** deliberately, not just `settings.input`: router conditions live at `settings.branches[].conditions[][].firstValue/.secondValue` and loop expressions at `settings.items`, and an `'input' in settings` guard silently skipped both (GIT-1075). Two things to respect when touching it: `settings.sourceCode` is excluded on purpose (it holds a user program, and a literal `{{ … }}` in a code step was being rewritten), and the remap must stay a **single pass** over the name map — applying one rename at a time rewrites its own output whenever a copied step's new name equals another copied step's old name, which happens on cross-flow paste into a flow that lacks the clipboard's names.
- **Paste order follows selection order, not flow order.** `_getActionsForCopy`'s `.sort((a, b) => allSteps.indexOf(a) - ...)` compares deep clones, so `indexOf` is always `-1` and the sort is a no-op. Harmless for a single step; it decides the chaining order for a multi-step paste.
diff --git a/packages/server/api/src/app/flows/flow-version/piece-upgrade.service.ts b/packages/server/api/src/app/flows/flow-version/piece-upgrade.service.ts
index 1b4a8428234..4b53cbd0bdb 100644
--- a/packages/server/api/src/app/flows/flow-version/piece-upgrade.service.ts
+++ b/packages/server/api/src/app/flows/flow-version/piece-upgrade.service.ts
@@ -243,9 +243,12 @@ async function resolveFlowVersionUpgrades({ flowVersion, log }: ResolveFlowVersi
}
async function sendUpgradeAuditEvent({ platformId, projectId, flowId, flowVersionId, decisions, log }: SendUpgradeAuditEventParams): Promise<void> {
- projectId = projectId ?? await flowRepo().findOneByOrFail({ id: flowId }).then((flow) => flow.projectId)
- platformId = platformId ?? await projectService(log).getPlatformId(projectId!)
- applicationEvents(log).sendUserEvent({ platformId, projectId }, {
+ const resolvedProjectId = projectId ?? (await flowRepo().findOneBy({ id: flowId }))?.projectId
+ if (isNil(resolvedProjectId)) {
+ return
+ }
+ const resolvedPlatformId = platformId ?? await projectService(log).getPlatformId(resolvedProjectId)
+ applicationEvents(log).sendUserEvent({ platformId: resolvedPlatformId, projectId: resolvedProjectId }, {
action: ApplicationEventName.FLOW_PIECES_UPGRADED,
data: {
flowId,
diff --git a/packages/server/api/test/integration/ce/flows/flow/flow-operations.test.ts b/packages/server/api/test/integration/ce/flows/flow/flow-operations.test.ts
index 77d31055e32..03437e16bd1 100644
--- a/packages/server/api/test/integration/ce/flows/flow/flow-operations.test.ts
+++ b/packages/server/api/test/integration/ce/flows/flow/flow-operations.test.ts
@@ -6,6 +6,7 @@ import {
FlowTriggerType,
FlowVersion,
FlowVersionState,
+ LATEST_FLOW_SCHEMA_VERSION,
PackageType,
PieceType,
PopulatedFlow,
@@ -794,6 +795,45 @@ describe('Flow Operations API', () => {
const persisted: PopulatedFlow = afterImport?.json()
expect(persisted.version.trigger.nextAction).toBeUndefined()
})
+
+ it('imports an old template whose piece version the upgrade register moves forward', async () => {
+ const ctx = await createTestContext(app!)
+
+ const createResponse = await ctx.post('/v1/flows', {
+ displayName: 'test flow',
+ projectId: ctx.project.id,
+ }, { query: { projectId: ctx.project.id } })
+ const flow: PopulatedFlow = createResponse?.json()
+
+ const response = await ctx.post(`/v1/flows/${flow.id}`, {
+ type: FlowOperationType.IMPORT_FLOW,
+ request: {
+ displayName: 'Event handler',
+ trigger: {
+ type: FlowTriggerType.PIECE,
+ name: 'trigger',
+ displayName: 'Catch Webhook',
+ valid: true,
+ lastUpdatedDate: new Date().toISOString(),
+ settings: {
+ pieceName: '@activepieces/piece-webhook',
+ pieceVersion: '0.1.33',
+ triggerName: 'catch_webhook',
+ input: { authType: 'none', authFields: {} },
+ propertySettings: {},
+ },
+ },
+ schemaVersion: '20',
+ notes: [],
+ },
+ })
+
+ expect(response?.statusCode).toBe(StatusCodes.OK)
+ const body: PopulatedFlow = response?.json()
+ expect(body.version.schemaVersion).toBe(LATEST_FLOW_SCHEMA_VERSION)
+ expect(body.version.trigger.type).toBe(FlowTriggerType.PIECE)
+ expect(body.version.trigger.settings.pieceVersion).not.toBe('0.1.33')
+ })
})
describe('POST /v1/flows/:id draft creation rollback', () => {
diff --git a/packages/server/api/test/unit/app/flows/flow-version/piece-upgrade.service.test.ts b/packages/server/api/test/unit/app/flows/flow-version/piece-upgrade.service.test.ts
new file mode 100644
index 00000000000..b3e5e20886e
--- /dev/null
+++ b/packages/server/api/test/unit/app/flows/flow-version/piece-upgrade.service.test.ts
@@ -0,0 +1,118 @@
+import {
+ FlowTriggerType,
+ FlowVersionState,
+ LATEST_FLOW_SCHEMA_VERSION,
+} from '@activepieces/shared'
+import type { FlowTrigger, FlowVersion } from '@activepieces/shared'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { migrateFlowVersionTemplate } from '../../../../../src/app/flows/flow-version/migrations'
+import { pieceUpgradeService } from '../../../../../src/app/flows/flow-version/piece-upgrade.service'
+import { system } from '../../../../../src/app/helper/system/system'
+
+const mockFlowFindOneBy = vi.fn()
+const mockSendUserEvent = vi.fn()
+
+vi.mock('../../../../../src/app/flows/flow-version/piece-upgrade-register', () => ({
+ pieceUpgradeRegister: {
+ lookup: vi.fn(async ({ pieceName, pieceVersion }: { pieceName: string, pieceVersion: string }) =>
+ pieceName === WEBHOOK_PIECE_NAME && pieceVersion === OLD_WEBHOOK_VERSION
+ ? { target: UPGRADED_WEBHOOK_VERSION }
+ : undefined),
+ resolveDecision: vi.fn(({ entry }: { entry: { target: string } }) => ({ outcome: 'upgraded', toVersion: entry.target })),
+ },
+}))
+
+vi.mock('../../../../../src/app/flows/flow/flow.repo', () => ({
+ flowRepo: () => ({
+ findOneBy: mockFlowFindOneBy,
+ }),
+}))
+
+vi.mock('../../../../../src/app/project/project-service', () => ({
+ projectService: vi.fn(() => ({
+ getPlatformId: vi.fn().mockResolvedValue('platform-1'),
+ })),
+}))
+
+vi.mock('../../../../../src/app/helper/application-events', () => ({
+ applicationEvents: vi.fn(() => ({
+ sendUserEvent: mockSendUserEvent,
+ })),
+}))
+
+describe('pieceUpgradeService.migrateFlowVersion', () => {
+ beforeEach(() => {
+ vi.clearAllMocks()
+ mockFlowFindOneBy.mockResolvedValue(null)
+ })
+
+ it('migrates a template that has no stored flow without sending an upgrade audit event', async () => {
+ const migrated = await migrateFlowVersionTemplate({
+ displayName: 'Handler flow',
+ trigger: webhookTrigger(),
+ schemaVersion: '20',
+ notes: [],
+ valid: false,
+ })
+
+ expect(migrated.schemaVersion).toBe(LATEST_FLOW_SCHEMA_VERSION)
+ expect(pieceVersionOf(migrated.trigger)).toBe(UPGRADED_WEBHOOK_VERSION)
+ expect(mockSendUserEvent).not.toHaveBeenCalled()
+ })
+
+ it('sends an upgrade audit event for a stored flow version resolved by its flow id', async () => {
+ mockFlowFindOneBy.mockResolvedValue({ id: 'flow-1', projectId: 'project-1' })
+
+ const result = await pieceUpgradeService(system.globalLogger()).migrateFlowVersion({ flowVersion: storedFlowVersion() })
+
+ expect(pieceVersionOf(result.flowVersion.trigger)).toBe(UPGRADED_WEBHOOK_VERSION)
+ expect(mockSendUserEvent).toHaveBeenCalledWith(
+ { platformId: 'platform-1', projectId: 'project-1' },
+ expect.objectContaining({ data: expect.objectContaining({ flowId: 'flow-1', flowVersionId: 'fv-1' }) }),
+ )
+ })
+})
+
+function webhookTrigger(): FlowTrigger {
+ return {
+ name: 'trigger',
+ valid: true,
+ displayName: 'Catch Webhook',
+ lastUpdatedDate: '2026-01-01T00:00:00Z',
+ type: FlowTriggerType.PIECE,
+ settings: {
+ pieceName: WEBHOOK_PIECE_NAME,
+ pieceVersion: OLD_WEBHOOK_VERSION,
+ triggerName: 'catch_webhook',
+ input: {},
+ propertySettings: {},
+ },
+ }
+}
+
+function storedFlowVersion(): FlowVersion {
+ return {
+ id: 'fv-1',
+ created: '2026-01-01T00:00:00Z',
+ updated: '2026-01-01T00:00:00Z',
+ flowId: 'flow-1',
+ displayName: 'Handler flow',
+ trigger: webhookTrigger(),
+ updatedBy: null,
+ valid: true,
+ schemaVersion: '23',
+ agentIds: [],
+ state: FlowVersionState.DRAFT,
+ connectionIds: [],
+ backupFiles: null,
+ notes: [],
+ }
+}
+
+function pieceVersionOf(trigger: FlowTrigger): string | undefined {
+ return trigger.type === FlowTriggerType.PIECE ? trigger.settings.pieceVersion : undefined
+}
+
+const WEBHOOK_PIECE_NAME = '@activepieces/piece-webhook'
+const OLD_WEBHOOK_VERSION = '0.1.33'
+const UPGRADED_WEBHOOK_VERSION = '0.1.36'