connect({ id, name }): "name" is required when connecting wi

Error message

connect({ id, name }): "name" is required when connecting without an agent id

What it means

connect() supports two forms: connect(agentId, options?) and connect({ id, name }). When using the object form without an agent id already known to Mastra (id provided but no name), the library requires a "name" because it creates/identifies the Slack app and needs a display name for the new agent binding.

Source

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

   */
  async connect(agentId: string, options?: SlackConnectOptions): Promise<ChannelConnectResult>;
  /**
   * Connect to Slack by creating a new Slack app for an arbitrary connection id
   * (no registered agent required — e.g. an AgentController or custom owner).
   * Since there is no agent to derive a display name from, `name` is required.
   *
   * @returns OAuth connect result with authorization URL for user redirect
   */
  async connect(options: SlackConnectOptions & { id: string; name: string }): Promise<ChannelConnectResult>;
  async connect(
    agentIdOrOptions: string | (SlackConnectOptions & { id: string; name: string }),
    maybeOptions?: SlackConnectOptions,
  ): Promise<ChannelConnectResult> {
    const isAgentIdForm = typeof agentIdOrOptions === 'string';
    const agentId = isAgentIdForm ? agentIdOrOptions : agentIdOrOptions.id;
    const options = isAgentIdForm ? maybeOptions : agentIdOrOptions;
    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`);
    }

View on GitHub (pinned to 75dd419e61)

Solutions

Pass a name in the options object: connect({ id, name: 'My Slack Agent' }).
If connecting an existing registered agent, use the string form: connect(agentId, options?).
Add runtime validation before calling connect to ensure either a string agentId or both id and name are provided.

Example fix

// before
await provider.connect({ id: 'agent-123' });
// after
await provider.connect({ id: 'agent-123', name: 'Support Agent' });

Defensive patterns

Strategy: validation

Validate before calling

function assertValidConnectArgs(agentIdOrOptions, maybeOptions) {
  if (typeof agentIdOrOptions === 'string') return;
  if (!agentIdOrOptions?.name) {
    throw new Error('object form requires { id, name }');
  }
}

Type guard

function isOptionsForm(x: unknown): x is { id: string; name: string } {
  return typeof x === 'object' && x !== null && 'id' in x && 'name' in x && typeof (x as any).name === 'string' && (x as any).name.length > 0;
}

Try / catch

try {
  await provider.connect({ id });
} catch (err) {
  if (err instanceof Error && err.message.includes('"name" is required')) {
    await provider.connect({ id, name: deriveNameFromId(id) });
  } else throw err;
}

Prevention

Prefer the string form connect(agentId) for existing registered agents.
Centralize connect calls in a helper that enforces the { id, name } shape.
Type your call sites with a discriminated union of the two connect forms.

When it happens

Trigger: Calling provider.connect({ id: 'some-id' }) (object form) with no name property and where the id is not resolved as an existing agent — the guard fires whenever the object form is used without a name.

Common situations: Migrating from the string form connect(agentId) to the options form and forgetting name; dynamically building the options object and omitting name; typing errors where the object form was intended for a new agent.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

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