{"record":{"id":"1b7d8309a582acc1","repo":"n8n-io/n8n","slug":"workflow-third-argument-is-settings-not-workflo","errorCode":null,"errorMessage":"workflow() third argument is settings, not workflow structure. Do not pass nodes or connections here — use .add() and .to() to build the workflow. Example: workflow('id', 'Name').add(trigger({...})).to(node({...}))","messagePattern":"workflow\\(\\) third argument is settings, not workflow structure\\. Do not pass nodes or connections here — use \\.add\\(\\) and \\.to\\(\\) to build the workflow\\. Example: workflow\\('id', 'Name'\\)\\.add\\(trigger\\((.+?)\\)\\)\\.to\\(node\\((.+?)\\)\\)","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/@n8n/workflow-sdk/src/workflow-builder.ts","lineNumber":1331,"sourceCode":"\t\t);\n\t}\n\tif (typeof name !== 'string') {\n\t\tconst receivedName = Array.isArray(name) ? 'an array' : typeof name;\n\t\tthrow new TypeError(\n\t\t\t// eslint-disable-next-line n8n-local-rules/no-interpolation-in-regular-string\n\t\t\t'workflow() requires (id: string, name: string). ' +\n\t\t\t\t`workflow() requires a string name as second argument, but received ${receivedName}. ` +\n\t\t\t\t\"Example: workflow('my-workflow-id', 'My Workflow Name')\",\n\t\t);\n\t}\n\tif (\n\t\toptions !== undefined &&\n\t\t(Array.isArray(options) ||\n\t\t\t(typeof options === 'object' &&\n\t\t\t\toptions !== null &&\n\t\t\t\t('nodes' in options || 'connections' in options)))\n\t) {\n\t\tthrow new TypeError(\n\t\t\t'workflow() third argument is settings, not workflow structure. ' +\n\t\t\t\t'Do not pass nodes or connections here — use .add() and .to() to build the workflow. ' +\n\t\t\t\t\"Example: workflow('id', 'Name').add(trigger({...})).to(node({...}))\",\n\t\t);\n\t}\n\tif (isWorkflowBuilderOptions(options)) {\n\t\treturn new WorkflowBuilderImpl(\n\t\t\tid,\n\t\t\tname,\n\t\t\toptions.settings,\n\t\t\tundefined,\n\t\t\tundefined,\n\t\t\tundefined,\n\t\t\tundefined,\n\t\t\toptions.registry,\n\t\t);\n\t}\n\treturn new WorkflowBuilderImpl(id, name, options);","sourceCodeStart":1313,"sourceCodeEnd":1349,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/workflow-sdk/src/workflow-builder.ts#L1313-L1349","documentation":"The third argument to workflow() is for WorkflowSettings (timezone, executionOrder, etc.) or a WorkflowBuilderOptions object (settings + registry). If the builder detects 'nodes' or 'connections' keys on that argument, it assumes the caller tried to pass a full workflow structure (the shape consumed by fromJSON) and throws, because workflow() builds incrementally via .add()/.to(). The guard prevents a silent no-op where settings would be ignored.","triggerScenarios":"Passing { nodes: [...], connections: {...} } as the third argument to workflow(), typically because the caller confused workflow() with fromJSON() or pasted a full workflow definition into the factory.","commonSituations":"Migrating from a JSON-import flow to the builder API and forgetting to switch from workflow(jsonStructure) to fromJSON(jsonStructure); copy-pasting a workflow body into the factory call.","solutions":["To import an existing workflow structure, use workflow.fromJSON({ nodes, connections, ... }) instead of workflow().","If you intended to pass settings, pass only setting keys (timezone, executionOrder, saveExecutionProgress, etc.) or a { settings, registry } options object.","Build the workflow incrementally: workflow('id', 'name').add(trigger({})).to(node({}))."],"exampleFix":"// before\nworkflow('id', 'name', { nodes: [...], connections: {...} }); // throws\n\n// after (import)\nworkflow.fromJSON({ id: 'id', name: 'name', nodes: [...], connections: {...} });\n\n// after (settings)\nworkflow('id', 'name', { timezone: 'UTC' });","handlingStrategy":"validation","validationCode":"function isWorkflowStructure(v: unknown): boolean {\n  return typeof v === 'object' && v !== null && ('nodes' in v || 'connections' in v);\n}\nif (isWorkflowStructure(thirdArg)) {\n  // use fromJSON instead of workflow()\n}","typeGuard":"function isWorkflowStructure(v: unknown): v is { nodes: unknown[]; connections: unknown } {\n  return typeof v === 'object' && v !== null && ('nodes' in v || 'connections' in v);\n}","tryCatchPattern":null,"preventionTips":["Use workflow.fromJSON() to import a full { nodes, connections } structure.","Pass only WorkflowSettings (timezone, executionOrder, ...) or { settings, registry } as the third argument to workflow().","Build incrementally with .add()/.to() rather than passing a workflow body to workflow()."],"tags":["workflow-builder","factory","api-misuse","validation"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}