ComposioHQ/composio · error · ValidationError

Failed to parse remote file response

Error message

Failed to parse remote file response

What it means

RemoteFile.parse() received data that does not conform to RemoteFileDataSchema. The SDK validates every remote-file payload from the API before constructing a RemoteFile, throwing ValidationError with the Zod issues as cause.

Source

Thrown at ts/packages/core/src/models/RemoteFile.ts:68

  readonly downloadUrl: string;

  constructor(data: RemoteFileData) {
    this.expiresAt = data.expiresAt;
    this.mountRelativePath = data.mountRelativePath;
    this.sandboxMountPrefix = data.sandboxMountPrefix;
    this.downloadUrl = data.downloadUrl;
  }

  /**
   * Parses an API response (snake_case) and returns a RemoteFile instance.
   * @param data - Raw API response with snake_case keys
   * @returns A RemoteFile instance
   * @throws ValidationError if the response shape is invalid
   */
  static parse(data: unknown): RemoteFile {
    const parsed = RemoteFileDataSchema.safeParse(data);
    if (!parsed.success) {
      throw new ValidationError('Failed to parse remote file response', {
        cause: parsed.error,
      });
    }
    return new RemoteFile(parsed.data);
  }

  /** Filename extracted from the mount path (e.g. "report.pdf" from "output/report.pdf") */
  get filename(): string {
    return platform.basename(this.mountRelativePath);
  }

  /**
   * Fetches the file content as a buffer.
   * @returns The file content as a Uint8Array
   * @throws RemoteFileDownloadError if the fetch fails
   */
  async buffer(): Promise<Uint8Array> {
    // SSRF guard: `downloadUrl` is set from an API response, so it is untrusted

View on GitHub (pinned to 64b1b85502)

Solutions

1. Check error.cause to identify missing/invalid fields
2. Fix the payload to include all required RemoteFileData fields with correct types
3. In tests, base mocks on a captured real response

Example fix

// before
const f = RemoteFile.parse({ id: 'f1' });
// after
const f = RemoteFile.parse({ id: 'f1', downloadUrl: 'https://...', filename: 'a.pdf', mountRelativePath: '/a.pdf' });

import { RemoteFileDataSchema } from '@composio/core';
const r = RemoteFileDataSchema.safeParse(data);
if (!r.success) throw new Error(JSON.stringify(r.error.issues));
const f = RemoteFile.parse(data);

const isRemoteFileData = (d: unknown): boolean => RemoteFileDataSchema.safeParse(d).success;

try { RemoteFile.parse(data); } catch (e) { if (e instanceof ValidationError && /remote file/.test(e.message)) { logIssues(e.cause); return null; } throw e; }

When it happens

Trigger: Passing a hand-crafted or modified object to RemoteFile.parse, or a backend response whose file fields (downloadUrl, filename, mountRelativePath, etc.) are missing or mistyped.

Common situations: Mocking API responses in tests with incomplete fixtures; API changes renaming file fields; serializing/deserializing a RemoteFile and feeding the altered shape back into parse().

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

• experimental_subAgent() schema must be a Zod schema or JSON
• Invalid arguments for local tool ${resolution.finalSlug}: ${
• Failed to parse manage connections config
• Failed to parse auth config create options
• Failed to parse auth config update data

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