# Migrate AWS SDK for JavaScript v2 to v3 in an Express S3 App

Yes. An agent moves an Express app from aws-sdk v2 to @aws-sdk/client-s3, tests each route against a local S3 stand-in, and opens a pull request.

[Run this on Rush](https://cloud.getrush.ai/run/migrate-aws-sdk-v2-to-v3/aws-sdk/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The `aws-sdk` package on npm now carries a deprecation notice saying v2 has reached end-of-support. The agent begins with what the app uses of it. In an app like adityajoshi12/s3-nodejs everything is in `app.js`: `aws.config.update` with a key, a secret and a region read from `ACCESS_KEY`, `ACCESS_SECRET` and `REGION`; one `new aws.S3()`; and four routes. `POST /upload` goes through `multer-s3` with `acl: "public-read"`. `GET /list`, `GET /download/:filename` and `DELETE /delete/:filename` call `listObjectsV2`, `getObject` and `deleteObject` with `.promise()`. `package.json` asks for `aws-sdk` `^2.1009.0` and `multer-s3` `^2.10.0`, and its `test` script is the npm placeholder that exits 1. There are no tests.

With no tests and no AWS account in the sandbox, the agent builds something to test against: a small HTTP server that speaks enough path-style S3 for these four operations, including an empty bucket and a missing key. Both SDK versions accept an `endpoint` override, so the same stand-in serves the old code and the new. On the old code it records the baseline. Listing works, download returns the bytes, delete answers 200. `GET /download/` with a key that does not exist ends the Node process: the rejected `NoSuchKey` is never caught in the async handler. That is how the app behaves today, and the agent writes it down before changing anything.

The port has three traps, and the stand-in finds each. First, `multer-s3` 2.x calls `s3.upload`, which a v3 client does not have, so passing the new `S3Client` to it fails with `this.s3.upload is not a function`. `multer-s3` 3.0.1 declares `@aws-sdk/client-s3` as a peer dependency and has to be upgraded in the same change. Second, v2 returns `Contents: []` for an empty bucket and v3 leaves `Contents` as `undefined`, so `r.Contents.map(...)` in `/list` throws on a bucket with nothing in it. Third, `Body` from `getObject` was a `Buffer` and is now a stream; `res.send(x.Body)` throws `Converting circular structure to JSON`. The agent pipes the stream to the response instead.

Error handling changes shape as well. The v2 error carried `code: 'NoSuchKey'`; the v3 error has `name: 'NoSuchKey'`, no `code`, and the HTTP status under `$metadata.httpStatusCode`. Since the missing-key crash was already there, the agent fixes it in the same pull request as a separately described commit: a 404 for `NoSuchKey` and a 500 for anything else. It then removes `aws-sdk`, runs `npm install`, and reports what the tree looks like. In this repository `node_modules` goes from 72 MB to 24 MB, of which the v2 SDK alone was 66 MB, and `npm audit` goes from 15 findings to 12. The 12 are in `multer` 1.4.3, `express` 4.17.1 and packages they pull in, and are a different upgrade.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Migrate this Node.js app from the aws-sdk v2 package to the modular AWS SDK v3 clients. Read package.json, the lockfile and every file that requires aws-sdk or a package that takes an S3 client, such as multer-s3. List each service client, each operation, every use of .promise(), aws.config.update, and each response field the code reads. You have no AWS credentials. Write a small local HTTP server that implements, path-style, just the S3 operations this app calls, with cases for an empty bucket and a missing key, and point the SDK at it with an endpoint override. Install from the lockfile and, on the unchanged code, call every route against it and record status, body and whether the process survives. Then port: one S3Client configured explicitly with region and credentials, Command objects with send(), streams for object bodies, and whatever version of multer-s3 works with a v3 client. Do not change route paths or response bodies. Repeat the same calls and show the results side by side. For each response field you listed, say whether its type or its value for an empty result changed. Remove aws-sdk, run npm install, and report node_modules size and npm audit before and after. Report the Node version the new packages require. Fix a crash you can reproduce only in a separate commit. Add the route checks as a test script. Open a pull request with every command and its output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

A pull request that changes `app.js`, `package.json` and `package-lock.json` and adds the S3 stand-in with a test script that calls the four routes. The description has the inventory of v2 calls, the before and after table for each route on a normal bucket, an empty bucket and a missing key, and the three failures the port passes through with their error text. It reports the install size and `npm audit` numbers, and that `@aws-sdk/client-s3` at the version installed declares `node >=20.0.0`.

A reviewer weighs what a stand-in cannot prove. It checks request shape and response handling, not IAM, regions or bucket policy, so the first call against a real bucket is still yours to make. One line deserves a look: the upload sends `x-amz-acl: public-read`, and Amazon S3's documentation says buckets created since April 2023 have ACLs disabled by default, in which case that upload is refused. The agent leaves the option as it found it and flags it. It also flags that the repository tracks a `.env` file, with empty values, and that `.gitignore` covers only `node_modules/`.

## Run it on every Monday morning

v2 no longer receives updates, so every service still on it is the same task waiting. In the console, add an automation to each Project with a `schedule` trigger, `cron` `0 9 * * 1` in your `timezone`, and a saved prompt that says: if `package.json` still depends on `aws-sdk`, do this migration; otherwise answer that there is nothing to do.

For a one-off sweep across many repositories, use an API key instead and send the body above once per repository, each with a `request_id` that is a UUID v5 of the repository name. The key's `max_concurrent` decides how many run at once, the rest are created `queued`, and a `webhook_url` on the key receives `run.completed` for each.

## Why run it on Rush?

This migration compiles at every wrong step. Nothing in JavaScript objects to a v3 client handed to an old `multer-s3`, to `.map` on a missing array, or to a stream passed to `res.send` until the request is made. Finding the three failures takes a server to send requests to, and the run builds one in its own sandbox, drives the old and new code through it, and keeps both sets of results.

It also needs no credentials of yours. The stand-in means no key is placed in the run and no test object is written to a real bucket. What comes back is a pull request whose claims are tied to recorded output, plus a test script the repository can keep.

## Frequently asked questions

### Does multer-s3 work with AWS SDK v3?

Version 3 of `multer-s3` does; it lists `@aws-sdk/client-s3` as a peer dependency. Version 2 expects the v2 client and fails with `this.s3.upload is not a function` when given an `S3Client`. The two upgrades have to land together.

### Why does my list route break on an empty bucket after migrating?

Because v3 omits `Contents` when there are no objects, where v2 returned an empty array. Code such as `r.Contents.map(...)` then throws. Default it with `r.Contents ?? []`; the agent finds these by testing each route against an empty bucket.

### How do I send an S3 object to the client in v3?

`Body` is a readable stream in Node, so pipe it: `x.Body.pipe(res)`, after setting the content type from the response. If you need the bytes in memory, `await x.Body.transformToByteArray()` gives them. Passing the stream to `res.send` fails.

### Can the codemod do this for me?

AWS publishes `aws-sdk-js-codemod`, which rewrites imports, client construction and `.promise()` calls, and the agent may use it as a first pass. It does not know that a library you pass the client to needs a new major version, or that an empty list changed type, which is what the route checks are for.

## More jobs like this: Upgrade dependencies weekly

- [Replace Axios With Native fetch in a Node.js Library](https://getrush.ai/run/migrate-axios-to-fetch/axios/)
- [Migrate From babel-eslint to @babel/eslint-parser](https://getrush.ai/run/migrate-babel-eslint-to-babel-eslint-parser/babel-eslint/)
- [Migrate a Go Project From Blackfriday to goldmark](https://getrush.ai/run/migrate-blackfriday-to-goldmark/blackfriday/)
- [Migrate From Bluebird to Native Promises in a Node.js Library](https://getrush.ai/run/migrate-bluebird-to-native-promises/bluebird/)
- [Replace body-parser With express.json() in an Express App](https://getrush.ai/run/migrate-body-parser-to-express-json/body-parser/)
- [Migrate From the Archived github.com/boltdb/bolt to go.etcd.io/bbolt in a Go Service](https://getrush.ai/run/migrate-boltdb-to-bbolt/boltdb/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
