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
TypeScript ai-agentai-agent-toolsai-agentsai-agents-frameworkmcpmcp-servermcp-toolsmcpsn8n-alternativeno-code-automationworkflowworkflow-automationworkflows
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.mdindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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'