Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | --- |
| 2 | title: 'SDKs remove legacy automatic file handling config' |
| 3 | description: 'SDKs remove deprecated `autoUploadDownloadFiles` / `auto_upload_download_files`. Automatic file handling is off unless you set `dangerouslyAllowAutoUploadDownloadFiles` / `dangerously_allow_auto_upload_download_files`. Minor releases.' |
| 4 | date: '2026-04-24' |
| 5 | --- |
| 6 | |
| 7 | The Composio SDKs no longer accept the legacy flags that previously controlled automatic file upload and download during tool execution. Automatic handling of `file_uploadable` fields stays **off by default**; you opt in with the explicit `dangerously*` option only. |
| 8 | |
| 9 | <Callout type="warn"> |
| 10 | **Breaking change** |
| 11 | |
| 12 | Those legacy properties are removed from the public constructors and config types. Code that still passes them must migrate. Anyone who **relied on the old default-on behavior** (no file flag in the constructor) must now **explicitly** set the `dangerously*` flag to `true` to keep automatic path/URL file handling. |
| 13 | </Callout> |
| 14 | |
| 15 | ### SDK versions (minor releases) |
| 16 | |
| 17 | | Package | Previous | This release | |
| 18 | | ------- | -------- | ------------ | |
| 19 | | TypeScript `@composio/core` | v0.6.11 | **v0.8.0** | |
| 20 | | Python `composio` | v0.11.6 | **v0.12.0** | |
| 21 | |
| 22 | Other `@composio/*` npm packages that depend on core are published as **patch** bumps in the same release train (via the changesets `updateInternalDependencies: "patch"` setting) so they pick up the updated `ComposioConfig` surface — they have no public-API changes of their own. |
| 23 | |
| 24 | ### Migration |
| 25 | |
| 26 | Earlier SDK versions treated automatic file upload/download for `file_uploadable` tool fields as **on by default** (TypeScript: `autoUploadDownloadFiles` defaulted to `true` when unset; Python followed the same idea for `auto_upload_download_files` in prior releases). **That default is now off.** If you still want that behavior, you must **explicitly** set `dangerouslyAllowAutoUploadDownloadFiles: true` (TypeScript) or `dangerously_allow_auto_upload_download_files=True` (Python). |
| 27 | |
| 28 | **TypeScript — before (legacy):** |
| 29 | |
| 30 | ```typescript |
| 31 | // @noErrors |
| 32 | // If you omitted autoUploadDownloadFiles, it used to default to true |
| 33 | new Composio({ |
| 34 | apiKey: process.env.COMPOSIO_API_KEY!, |
| 35 | }); |
| 36 | |
| 37 | // Equivalent when you set it explicitly: |
| 38 | new Composio({ |
| 39 | apiKey: process.env.COMPOSIO_API_KEY!, |
| 40 | autoUploadDownloadFiles: true, |
| 41 | }); |
| 42 | ``` |
| 43 | |
| 44 | **TypeScript — going forward** (set `true` to match either legacy pattern above): |
| 45 | |
| 46 | ```typescript |
| 47 | // @noErrors |
| 48 | new Composio({ |
| 49 | apiKey: process.env.COMPOSIO_API_KEY!, |
| 50 | dangerouslyAllowAutoUploadDownloadFiles: true, |
| 51 | }); |
| 52 | ``` |
| 53 | |
| 54 | To leave automatic file handling **off** (new default), omit `dangerouslyAllowAutoUploadDownloadFiles` or set it to `false`. |
| 55 | |
| 56 | **Python — before (legacy):** |
| 57 | |
| 58 | ```python |
| 59 | # If you omitted auto_upload_download_files, it used to default to True (prior releases) |
| 60 | Composio(api_key="...") |
| 61 | |
| 62 | # Equivalent when you set it explicitly: |
| 63 | Composio(api_key="...", auto_upload_download_files=True) |
| 64 | ``` |
| 65 | |
| 66 | **Python — going forward** (set `True` to match either legacy pattern above): |
| 67 | |
| 68 | ```python |
| 69 | Composio(api_key="...", dangerously_allow_auto_upload_download_files=True) |
| 70 | ``` |
| 71 | |
| 72 | If you construct `ToolRouterSession` directly (unusual), the keyword argument is now `dangerously_allow_auto_upload_download_files` instead of `auto_upload_download_files`. |
| 73 | |
| 74 | ### Local paths must live inside an allowlisted directory |
| 75 | |
| 76 | Even with `dangerouslyAllowAutoUploadDownloadFiles` enabled, the SDK will **only** auto-upload local file paths that resolve inside an allowlisted directory. Paths outside the allowlist are rejected with `ComposioFileUploadPathNotAllowed` (TypeScript) / `FileUploadPathNotAllowed` (Python) before any file is read or sent. |
| 77 | |
| 78 | This is a behavior change. Earlier SDK versions had no allowlist: any local path the legacy default-on flag saw was uploaded. |
| 79 | |
| 80 | **Default allowlist:** |
| 81 | |
| 82 | | `fileUploadDirs` value | Effective allowlist | |
| 83 | | ---------------------- | ------------------- | |
| 84 | | omitted / `undefined` | `[ <home>/.composio/temp ]` (default staging dir) | |
| 85 | | `false` | `[]` — **all** local paths rejected (URLs and `File` objects still work) | |
| 86 | | `[]` | `[]` — same as `false`; explicit "no local paths" | |
| 87 | | `[<dir1>, <dir2>, …]` | exactly those directories (replaces the default; `~` is expanded, paths are `realpath`-resolved, comparison is on a path-component boundary) | |
| 88 | |
| 89 | URLs (`http://…` / `https://…`) and JavaScript `File` objects are **not** subject to the allowlist — only local string paths are. |
| 90 | |
| 91 | **TypeScript:** |
| 92 | |
| 93 | ```typescript |
| 94 | // @noErrors |
| 95 | // Match the *broadest* legacy behavior: auto-upload on, allowlist widened to |
| 96 | // the directories your code actually reads from. Set this scope as tightly |
| 97 | // as you can — every path inside these dirs becomes uploadable to Composio. |
| 98 | new Composio({ |
| 99 | apiKey: process.env.COMPOSIO_API_KEY!, |
| 100 | dangerouslyAllowAutoUploadDownloadFiles: true, |
| 101 | fileUploadDirs: ['/srv/uploads', '~/data/inbox'], |
| 102 | }); |
| 103 | |
| 104 | // Disallow local-path uploads entirely; the SDK will only stage URLs and |
| 105 | // File objects, and reject string paths outright. |
| 106 | new Composio({ |
| 107 | apiKey: process.env.COMPOSIO_API_KEY!, |
| 108 | dangerouslyAllowAutoUploadDownloadFiles: true, |
| 109 | fileUploadDirs: false, |
| 110 | }); |
| 111 | ``` |
| 112 | |
| 113 | **Python:** |
| 114 | |
| 115 | ```python |
| 116 | # Equivalent of the TypeScript example above. |
| 117 | Composio( |
| 118 | api_key="...", |
| 119 | dangerously_allow_auto_upload_download_files=True, |
| 120 | file_upload_dirs=["/srv/uploads", "~/data/inbox"], |
| 121 | ) |
| 122 | |
| 123 | # Reject all local paths. |
| 124 | Composio( |
| 125 | api_key="...", |
| 126 | dangerously_allow_auto_upload_download_files=True, |
| 127 | file_upload_dirs=False, |
| 128 | ) |
| 129 | ``` |
| 130 | |
| 131 | **Manual staging (TypeScript only):** |
| 132 | |
| 133 | If you don't want to widen the allowlist, the TypeScript SDK lets you stage files yourself via `composio.files.upload(...)`. That call **bypasses the allowlist** by design (the caller is expected to control the path), and the returned `{ name, mimetype, s3key }` descriptor can be passed straight into `tools.execute`: |
| 134 | |
| 135 | ```typescript |
| 136 | // @noErrors |
| 137 | const staged = await composio.files.upload({ |
| 138 | file: '/anywhere/on/disk/report.pdf', |
| 139 | toolSlug: 'GOOGLEDRIVE_UPLOAD_FILE', |
| 140 | toolkitSlug: 'googledrive', |
| 141 | }); |
| 142 | |
| 143 | await composio.tools.execute('GOOGLEDRIVE_UPLOAD_FILE', { |
| 144 | userId: 'user-1', |
| 145 | arguments: { file_to_upload: staged }, |
| 146 | }); |
| 147 | ``` |
| 148 | |
| 149 | The Python SDK does not currently expose a top-level manual-staging API; opt in with `dangerously_allow_auto_upload_download_files=True` and configure `file_upload_dirs` to cover the directories your code reads from. |
| 150 | |
| 151 | ### What else changed |
| 152 | |
| 153 | - TypeScript: `resolveAutoUploadDownloadFilesEnabled` only considers `dangerouslyAllowAutoUploadDownloadFiles`; the old deprecation warning for the legacy property is removed. |
| 154 | - Python: the small `composio.utils.auto_upload_download` helper that merged legacy + new flags is removed; `Tools` and `ToolRouter` take only the explicit opt-in boolean. |
| 155 | |
| 156 | Documentation for [executing tools](/docs/tools-direct/executing-tools) and the TypeScript [Composio reference](/reference/sdk-reference/typescript/composio) is updated to describe defaults and the opt-in flag. |