{"record":{"id":"47e38a1747e668b0","repo":"ComposioHQ/composio","slug":"failed-to-parse-remote-file-properties","errorCode":null,"errorMessage":"Failed to parse remote file properties","messagePattern":"Failed to parse remote file properties","errorType":"validation","errorClass":"ValidationError","httpStatus":null,"severity":"error","filePath":"ts/packages/core/src/models/ToolRouterSessionFileMount.ts","lineNumber":276,"sourceCode":"      throw new Error(`Failed to upload file: ${uploadResponse.statusText}`);\n    }\n\n    const createDownloadURLResponse = await this.client.toolRouter.session.files.createDownloadURL(\n      uploadOptions.data.mountId,\n      {\n        session_id: this.sessionId,\n        mount_relative_path: (uploadURLData as { mount_relative_path: string }).mount_relative_path,\n      }\n    );\n\n    const downloadData =\n      typeof createDownloadURLResponse === 'object' && 'body' in createDownloadURLResponse\n        ? (createDownloadURLResponse as { body: unknown }).body\n        : createDownloadURLResponse;\n\n    const parsed = RemoteFileDataSchema.safeParse(downloadData);\n    if (!parsed.success) {\n      throw new ValidationError('Failed to parse remote file properties', {\n        cause: parsed.error,\n      });\n    }\n\n    return new RemoteFile(parsed.data);\n  }\n\n  /**\n   * Downloads a file from the session's file mount to the local filesystem.\n   *\n   * Retrieves a file stored in the session's virtual filesystem (e.g., one produced\n   * by a tool or previously uploaded) and saves it to the specified local path.\n   *\n   * @param filePath - The path of the file on the mount to download, or the local path where the file should be saved (implementation-specific).\n   * @param options - Optional configuration for the download.\n   * @param options.mountId - The ID of the file mount to download from. Defaults to `\"files\"` when omitted.\n   * @returns The downloaded file data or path (implementation-specific).\n   *","sourceCodeStart":258,"sourceCodeEnd":294,"githubUrl":"https://github.com/ComposioHQ/composio/blob/64b1b85502b1beeb2379e6c9e8bf1104504fa637/ts/packages/core/src/models/ToolRouterSessionFileMount.ts#L258-L294","documentation":"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.","triggerScenarios":"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.","commonSituations":"Upgrading the backend but not the SDK (or vice versa), API contract drift, or truncated/malformed JSON from intermediaries.","solutions":["Upgrade @composio/core to the latest version so its schemas match the current API response","Inspect error.cause (ZodError) to identify which field mismatched and report it if the SDK is current","Retry once to rule out transient malformed responses"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"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; }","preventionTips":["Keep @composio/core updated alongside backend changes","Pin SDK versions deliberately and test after upgrades"],"tags":["validation","zod","api-contract","file-mount","upload"],"backgroundTag":"schema-validation-failed","analyzedSha":"64b1b85502b1beeb2379e6c9e8bf1104504fa637","analyzedAt":"2026-08-28T15:39:33.623Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}