ComposioHQ/composio · error · ValidationError

Failed to parse tool router session files mount download opt

Error message

Failed to parse tool router session files mount download options

What it means

The download() method validates its options argument with ToolRouterSessionFilesMountDownloadOptionsSchema before issuing any request. If options do not match (e.g. mountId missing/invalid), a ValidationError with the Zod issues as cause is thrown. This fails fast before any network activity.

Source

Thrown at ts/packages/core/src/models/ToolRouterSessionFileMount.ts:318

   *
   * @example
   * ```typescript
   * // Download from a custom mount
   * await session.experimental.files.download('/exports/data.json', {
   *   mountId: 'custom-mount',
   * });
   * ```
   */
  async download(
    filePath: string,
    options?: ToolRouterSessionFilesMountDownloadOptions
  ): Promise<RemoteFile> {
    const downloadOptions = ToolRouterSessionFilesMountDownloadOptionsSchema.safeParse(
      options ?? {}
    );

    if (!downloadOptions.success) {
      throw new ValidationError(
        'Failed to parse tool router session files mount download options',
        {
          cause: downloadOptions.error,
        }
      );
    }

    const createDownloadURLResponse = await this.client.toolRouter.session.files.createDownloadURL(
      downloadOptions.data.mountId,
      {
        session_id: this.sessionId,
        mount_relative_path: filePath,
      }
    );

    const downloadURLData =
      typeof createDownloadURLResponse === 'object' && 'body' in createDownloadURLResponse
        ? (createDownloadURLResponse as { body: unknown }).body

View on GitHub (pinned to 64b1b85502)

Solutions

1. Pass a valid mountId string in the download options
2. Verify the mount id comes from the file mount creation/listing, not the session id
3. Read error.cause (ZodError) issues to find the offending field

Example fix

// before
await mount.download('/data/file.csv', { mountId: sessionId });
// after
await mount.download('/data/file.csv', { mountId: mountId });

const ok = typeof opts?.mountId === 'string' && opts.mountId.length > 0;
if (!ok) throw new Error('mountId required');
await mount.download(path, opts);

const isDownloadOpts = (o: unknown): o is { mountId: string } =>
  typeof o === 'object' && o !== null && typeof (o as any).mountId === 'string';

try { await mount.download(path, opts); } catch (e) { if (e instanceof ValidationError) console.error(e.cause?.issues); throw e; }

When it happens

Trigger: Calling mount.download(remotePath, { mountId: ... }) with a missing, undefined, or non-string mountId, or otherwise schema-invalid options object.

Common situations: Reusing an options object built for a different mount, destructuring that drops mountId, or passing the session id instead of the mount id.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Failed to parse tool router session files mount upload optio
• Failed to parse tool router session files mount delete optio
• Invalid arguments for local tool ${resolution.finalSlug}: ${
• Failed to parse create connected account link options
• Invalid parameters passed to create mcp config

AI-assisted analysis of ComposioHQ/composio@64b1b85502 (2026-08-28). Data as JSON: /api/errors/3fd3f40fcc64c8c8. Report an issue: GitHub.