ComposioHQ/composio · error · ValidationError

Failed to parse remote file properties

Error message

Failed to parse remote file properties

What it means

Once a file is uploaded and a download URL is created, the SDK parses the API response body against RemoteFileDataSchema. If the backend returns an unexpected shape (missing or wrongly-typed remote file fields), a ValidationError wrapping the Zod issues is thrown. This indicates an API/SDK version mismatch or an unexpected server response rather than caller error.

Source

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

      throw new Error(`Failed to upload file: ${uploadResponse.statusText}`);
    }

    const createDownloadURLResponse = await this.client.toolRouter.session.files.createDownloadURL(
      uploadOptions.data.mountId,
      {
        session_id: this.sessionId,
        mount_relative_path: (uploadURLData as { mount_relative_path: string }).mount_relative_path,
      }
    );

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

    const parsed = RemoteFileDataSchema.safeParse(downloadData);
    if (!parsed.success) {
      throw new ValidationError('Failed to parse remote file properties', {
        cause: parsed.error,
      });
    }

    return new RemoteFile(parsed.data);
  }

  /**
   * Downloads a file from the session's file mount to the local filesystem.
   *
   * Retrieves a file stored in the session's virtual filesystem (e.g., one produced
   * by a tool or previously uploaded) and saves it to the specified local path.
   *
   * @param filePath - The path of the file on the mount to download, or the local path where the file should be saved (implementation-specific).
   * @param options - Optional configuration for the download.
   * @param options.mountId - The ID of the file mount to download from. Defaults to `"files"` when omitted.
   * @returns The downloaded file data or path (implementation-specific).
   *

View on GitHub (pinned to 64b1b85502)

Solutions

1. Upgrade @composio/core to the latest version so its schemas match the current API response
2. Inspect error.cause (ZodError) to identify which field mismatched and report it if the SDK is current
3. Retry once to rule out transient malformed responses

try { const f = await mount.upload(file, opts); } catch (e) { if (e instanceof ValidationError && /remote file properties/.test(e.message)) { /* log e.cause issues, upgrade SDK */ } throw e; }

When it happens

Trigger: Calling upload() successfully at the transport level but the createDownloadURL response body does not conform to RemoteFileDataSchema — e.g. after a backend contract change or when using an outdated SDK version against a newer API.

Common situations: Upgrading the backend but not the SDK (or vice versa), API contract drift, or truncated/malformed JSON from intermediaries.

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 file delete response
• Failed to parse tool router session files mount download opt
• Failed to parse tool router session files mount delete optio
• Not a file: {file}. Please provide a valid file path.

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