mastra-ai/mastra · error

Agent "${agentId}" not found

Error message

Agent "${agentId}" not found

What it means

When connect() is called in the string form connect(agentId), the id must resolve to a registered Agent on the attached Mastra instance via #resolveAgent(). If it does not, the installation would have no valid owner, so the provider throws with the offending id.

Source

Thrown at channels/slack/src/provider.ts:1057

    if (!isAgentIdForm && !agentIdOrOptions.name) {
      throw new Error('connect({ id, name }): "name" is required when connecting without an agent id');
    }

    const client = this.#requireManifestClient();

    const baseUrl = this.#getBaseUrl();
    if (!baseUrl) {
      throw new Error(
        'SlackProvider baseUrl not set. Configure studioHost/studioProtocol/studioPort in Mastra server config, or call setBaseUrl().',
      );
    }

    // In the agentId form, the agent must exist. In the options form the id may
    // belong to a registered agent or an AgentController — resolve which one so
    // the installation records who owns it.
    const agent = this.#resolveAgent(agentId);
    if (isAgentIdForm && !agent) {
      throw new Error(`Agent "${agentId}" not found`);
    }
    let ownerType: SlackOwnerType = 'agent';
    if (!isAgentIdForm && !agent) {
      const controller = this.#resolveAgentController(agentId);
      if (!controller) {
        throw new Error(`No agent or agent controller found with id "${agentId}"`);
      }
      ownerType = 'agentController';
    }

    // If there's already a pending installation, return its authorization URL
    // instead of creating a duplicate Slack app
    const storage = await this.#getStorage();
    const existingRecord = await storage.getInstallationByAgent(PLATFORM, agentId);
    if (existingRecord?.status === 'pending') {
      try {
        const pending = this.#parsePendingInstallation(existingRecord);
        const decrypted = this.#decryptPendingInstallation(pending);

View on GitHub (pinned to 75dd419e61)

Solutions

1. Register the agent on the Mastra instance: new Mastra({ agents: { 'my-agent': agent } }).
2. Fix the id typo in the connect() call to match the registered agent key.
3. Verify provider.__attach() received the same Mastra instance that holds the agent.

Example fix

// before
await provider.connect('supprot-agent');
// after
await provider.connect('support-agent'); // matches agents key in new Mastra({ agents: { 'support-agent': agent } })

const agent = mastra.getAgent?.(agentId);
if (!agent) {
  throw new Error(`Register agent "${agentId}" on the Mastra instance before connecting`);
}

function agentExists(mastra: Mastra, id: string): boolean {
  return Object.keys(mastra.getAgents?.() ?? {}).includes(id);
}

try {
  await provider.connect(agentId);
} catch (err) {
  if (err instanceof Error && err.message === `Agent "${agentId}" not found`) {
    console.error(`Available agents: ${Object.keys(mastra.getAgents()).join(', ')}`);
  } else throw err;
}

When it happens

Trigger: provider.connect('my-agent') where 'my-agent' is not a key in the Mastra instance's agents map — typo, agent not registered, or agent registered on a different Mastra instance than the one attached to the provider.

Common situations: Renaming an agent without updating the connect call; connecting before the agent is registered; multiple Mastra instances (e.g. dev vs worker) where the provider is attached to one that lacks the agent.

Related errors

• No agent or agent controller found with id "${agentId}"
• App creation failed: ${errorDetails}
• App manifest update failed: ${errorDetails}
• connect({ id, name }): "name" is required when connecting wi
• Agent ID is required

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/cff82764199c2cda. Report an issue: GitHub.