{"record":{"id":"80239e8afe1364c8","repo":"n8n-io/n8n","slug":"agent-this-name-requires-instructions","errorCode":null,"errorMessage":"Agent \"${this.name}\" requires instructions","messagePattern":"Agent \"(.+?)\" requires instructions","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/@n8n/agents/src/sdk/agent.ts","lineNumber":965,"sourceCode":"\n\tprivate async cleanupRuntime(active: ActiveRuntime): Promise<void> {\n\t\tif (!this.activeRuntimes.delete(active)) return;\n\t\tactive.bus.dispose();\n\t\tawait active.runtime.dispose();\n\t}\n\n\tprivate toMessages(input: string | AgentMessage[]): AgentMessage[] {\n\t\tif (Array.isArray(input)) return input;\n\t\treturn [{ role: 'user', content: [{ type: 'text', text: input }] }];\n\t}\n\n\t/** @internal Validate configuration and produce an AgentRuntime. Overridden by the execution engine. */\n\tprotected async build(): Promise<AgentRuntimeConfig> {\n\t\tif (!this.modelConfig) {\n\t\t\tthrow new Error(`Agent \"${this.name}\" requires a model`);\n\t\t}\n\t\tif (!this.instructionsText) {\n\t\t\tthrow new Error(`Agent \"${this.name}\" requires instructions`);\n\t\t}\n\n\t\tconst finalTools = [...this.tools];\n\t\tconst configuredDeferredTools = [...this.deferredTools];\n\n\t\tif (this.workspaceInstance) {\n\t\t\tconst wsTools = this.workspaceInstance.getTools();\n\t\t\tfinalTools.push(...wsTools);\n\t\t}\n\n\t\tconst finalStaticTools = finalTools;\n\t\tconst finalDeferredTools = configuredDeferredTools;\n\n\t\t// Validate checkpoint requirement from static tools and known MCP approval config\n\t\t// before attempting any network connections (allows fast failure).\n\t\tconst staticNeedsCheckpoint =\n\t\t\tfinalStaticTools.some((t) => t.suspendSchema) ||\n\t\t\tfinalDeferredTools.some((t) => t.suspendSchema);","sourceCodeStart":947,"sourceCodeEnd":983,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/agents/src/sdk/agent.ts#L947-L983","documentation":"Thrown by Agent.build() when instructionsText has not been set. Every agent requires a system instruction that defines its role, behavior, and constraints — without it the model has no persona or task framing. The build method enforces this before constructing the runtime.","triggerScenarios":"Calling agent.run() or agent.build() without first calling agent.instructions('...') or agent.instructionsText = '...'. Also triggered if instructions were set to an empty string or conditionally skipped.","commonSituations":"Dynamically generating instructions from a template that produced an empty string. Conditionally setting instructions based on a feature flag that was off. Copying agent setup and omitting the instructions call. Confusing instructions (system prompt) with the user message.","solutions":["Call agent.instructions('...') with a non-empty string before building or running.","Ensure instruction templates always produce non-empty output; add a fallback default.","Validate that instructionsText is truthy before calling build."],"exampleFix":"// before\nconst agent = new Agent('my-agent').model(myModel);\nawait agent.run('Hello');\n// after\nconst agent = new Agent('my-agent')\n  .model(myModel)\n  .instructions('You are a helpful assistant.');\nawait agent.run('Hello');","handlingStrategy":"validation","validationCode":"if (!instructions || instructions.trim().length === 0) {\n  throw new Error('Instructions must be a non-empty string');\n}\nagent.instructions(instructions);","typeGuard":"function isNonEmptyString(s: unknown): s is string {\n  return typeof s === 'string' && s.trim().length > 0;\n}","tryCatchPattern":null,"preventionTips":["Always call agent.instructions('...') with a non-empty string.","Ensure instruction templates always produce non-empty output with a fallback.","Validate instructionsText is truthy before build."],"tags":["agent","instructions","configuration","build"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}