n8n-io/n8n · error · Error

Agent "${this.name}" requires instructions

Error message

Agent "${this.name}" requires instructions

What it means

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.

Source

Thrown at packages/@n8n/agents/src/sdk/agent.ts:965

	private async cleanupRuntime(active: ActiveRuntime): Promise<void> {
		if (!this.activeRuntimes.delete(active)) return;
		active.bus.dispose();
		await active.runtime.dispose();
	}

	private toMessages(input: string | AgentMessage[]): AgentMessage[] {
		if (Array.isArray(input)) return input;
		return [{ role: 'user', content: [{ type: 'text', text: input }] }];
	}

	/** @internal Validate configuration and produce an AgentRuntime. Overridden by the execution engine. */
	protected async build(): Promise<AgentRuntimeConfig> {
		if (!this.modelConfig) {
			throw new Error(`Agent "${this.name}" requires a model`);
		}
		if (!this.instructionsText) {
			throw new Error(`Agent "${this.name}" requires instructions`);
		}

		const finalTools = [...this.tools];
		const configuredDeferredTools = [...this.deferredTools];

		if (this.workspaceInstance) {
			const wsTools = this.workspaceInstance.getTools();
			finalTools.push(...wsTools);
		}

		const finalStaticTools = finalTools;
		const finalDeferredTools = configuredDeferredTools;

		// Validate checkpoint requirement from static tools and known MCP approval config
		// before attempting any network connections (allows fast failure).
		const staticNeedsCheckpoint =
			finalStaticTools.some((t) => t.suspendSchema) ||
			finalDeferredTools.some((t) => t.suspendSchema);

View on GitHub (pinned to 5ac6606e81)

Solutions

1. Call agent.instructions('...') with a non-empty string before building or running.
2. Ensure instruction templates always produce non-empty output; add a fallback default.
3. Validate that instructionsText is truthy before calling build.

Example fix

// before
const agent = new Agent('my-agent').model(myModel);
await agent.run('Hello');
// after
const agent = new Agent('my-agent')
  .model(myModel)
  .instructions('You are a helpful assistant.');
await agent.run('Hello');

if (!instructions || instructions.trim().length === 0) {
  throw new Error('Instructions must be a non-empty string');
}
agent.instructions(instructions);

function isNonEmptyString(s: unknown): s is string {
  return typeof s === 'string' && s.trim().length > 0;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Agent "${this.name}" requires a model
• Invalid memory configuration. Use: new Memory() for in-proce
• toolCallConcurrency must be a positive integer or Infinity
• Agent "${this.name}" has tools requiring approval or suspend
• Static tool name collision — the following tool names resolv

AI-assisted analysis of n8n-io/n8n@5ac6606e81 (2026-08-12). Data as JSON: /api/errors/80239e8afe1364c8. Report an issue: GitHub.