ruvnet/ruflo · error

Agent config must include id, name, and type

Error message

Agent config must include id, name, and type

What it means

Thrown by the AgenticFlowAgent constructor (v3/@claude-flow/integration/src/agentic-flow-agent.ts:313) when the AgentConfig lacks a truthy id, name, or type. These three fields are mandatory because they identify the agent in the swarm, in events, and in routing.

Source

Thrown at v3/@claude-flow/integration/src/agentic-flow-agent.ts:313

   */
  private delegationEnabled: boolean = false;

  /**
   * Extended configuration
   */
  private extendedConfig: AgentConfig;

  /**
   * Create a new AgenticFlowAgent instance
   *
   * @param config - Agent configuration
   */
  constructor(config: AgentConfig) {
    super();

    // Validate required fields
    if (!config.id || !config.name || !config.type) {
      throw new Error('Agent config must include id, name, and type');
    }

    this.id = config.id;
    this.name = config.name;
    this.type = config.type;
    this.config = config;
    this.extendedConfig = config;
    this.createdAt = new Date();
    this.lastActivity = new Date();

    // Initialize metrics
    this.metrics = {
      tasksCompleted: 0,
      tasksFailed: 0,
      avgTaskDuration: 0,
      errorCount: 0,
      uptime: 0,
    };

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Provide non-empty id, name, and type in the AgentConfig literal passed to the constructor.
2. Validate agent definition objects at load time (config file, API payload) with a schema check before constructing agents.
3. Add defaults in your factory (e.g. id = `agent-${crypto.randomUUID()}`) when a field is genuinely optional in your domain.
4. Check for empty strings too — the guard is truthiness, so '' fails exactly like undefined.

Example fix

// before
const agent = new AgenticFlowAgent({ name: 'coder' } as AgentConfig);

// after
const agent = new AgenticFlowAgent({
  id: `coder-${Date.now()}`,
  name: 'coder',
  type: 'coder',
  ...rest,
});

function requireAgentFields(cfg: unknown): asserts cfg is { id: string; name: string; type: string } {
  const c = cfg as Record<string, unknown>;
  for (const k of ['id', 'name', 'type']) {
    if (typeof c[k] !== 'string' || (c[k] as string).length === 0) {
      throw new Error(`agent config missing ${k}`);
    }
  }
}

function isValidAgentConfig(c: unknown): c is { id: string; name: string; type: string } {
  return !!c && typeof c === 'object' &&
    typeof (c as any).id === 'string' && (c as any).id.length > 0 &&
    typeof (c as any).name === 'string' && (c as any).name.length > 0 &&
    typeof (c as any).type === 'string' && (c as any).type.length > 0;
}

try {
  agent = new AgenticFlowAgent(cfg);
} catch (e) {
  if ((e as Error).message === 'Agent config must include id, name, and type') {
    throw new ConfigError('agent definition incomplete', cfg);
  }
  throw e;
}

When it happens

Trigger: new AgenticFlowAgent({}) or a config built from unvalidated JSON/env where id/name/type is missing, empty string, or undefined; destructuring mistakes that rename the keys; configs deserialized from YAML where the keys are nested one level too deep.

Common situations: Agent definitions loaded from a config file that drifted from the schema; programmatic agent factories with optional parameters leaking through; copy-pasting an agent template and forgetting to change the id.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

• SemanticRouter requires a dimension in config
• Worker config must include id
• Invalid inputDim: ${this.config.inputDim}. Must be positive.
• Invalid outputDim: ${this.config.outputDim}. Must be positiv
• Invalid numHeads: ${this.config.numHeads}. Must be positive.

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/278ffce9d2ab3c38. Report an issue: GitHub.