skip to content

In Cloudflare Workers, what does setting placement mode to smart change, and which Workers does it actually help?

level: middleimportance: nice to knowfreq 25%

answer

  1. default: nearest the visitor
  2. chatty backend calls
  3. fetch handler only
  4. cf-placement header

basics

~20 s

Smart Placement lets Cloudflare run a Worker's fetch handler near the back ends it calls, instead of nearest the visitor, when measurements show that is faster. It helps Workers making several round trips to one distant backend, not Workers answering at the edge.

solid answer

~40 s

By default a Worker runs in the Cloudflare data center closest to the visitor. With `"placement": { "mode": "smart" }`, Cloudflare measures the Worker's request duration in candidate locations and forwards requests to one that is significantly faster once the forwarding hop is included; otherwise it stays local. That pays off when one request makes several sequential calls to a single-region backend, such as an image-metadata Worker running three database queries per request. A geolocation redirect Worker that answers from request data gains nothing. Limits: only the fetch handler is placed, not RPC methods or named entrypoints; only locations where the Worker has run are considered; analysis can take 15 minutes and needs steady traffic; 1% of requests stay unplaced as a baseline. The `cf-placement` header, such as `remote-LHR`, shows where a request ran.

code

json · 8 lines
json
{
  "name": "image-metadata",
  "main": "src/index.js",
  "compatibility_date": "2026-10-01",
  "placement": {
    "mode": "smart"
  }
}

go deeper

for a junior

Recall that Workers run nearest the visitor by default and that placement mode smart can run them nearer their back ends instead.

for a middle

Explain the trade Smart Placement makes, one long hop for many short ones, and which Workers benefit: those making several round trips to one region's backend.

for a senior

Know the limits, fetch handlers only, previously seen locations only, analysis delay and the baseline, and verify the effect with placement status and request duration analytics.

for a principal

Decide when to split edge logic from data logic into separate Workers so that only the data-heavy part is placed, and when an explicit hint beats automatic analysis.

## Default: run nearest the visitor A request to a Cloudflare Worker lands at the data center nearest the visitor, and by default the Worker runs right there. For a Worker that answers from the edge, using only the request, a cached value or a fast lookup, that is ideal. For a Worker that talks to a database in one region several times per request, it can be the worst choice: a visitor in Sydney hitting a Worker in Sydney that makes four sequential round trips to a database in Frankfurt pays the Sydney-Frankfurt latency four times. **Placement** lets the Worker run elsewhere. Moving the Worker next to the database trades one long hop (visitor to Worker) for many short ones (Worker to database). The arithmetic is easy to do on a whiteboard. Call the round-trip time between the two cities R. Run at the edge, four sequential queries cost about 4R on top of the visitor's short hop to the nearby data center. Placed near the database, the request pays roughly one R to forward the request and return the response, and the four queries become short local trips. The more sequential round trips a request makes to the same back end, the more placement saves; with zero or one call, it saves nothing and may add a hop. ## How Smart Placement decides Smart Placement is enabled per Worker in the Wrangler configuration with `placement.mode` set to `smart`, or in the dashboard under Settings > General > Placement. Then: 1. Cloudflare regularly analyses the Worker's **request duration** in the locations where it runs. 2. For each candidate location it weighs the Worker's performance there against the latency added by forwarding the request. 3. If a candidate is significantly faster, requests are forwarded to it; otherwise the Worker keeps running in the default location nearest the request. 4. By default 1% of requests are not routed with Smart Placement, to serve as a comparison baseline. The analysis can take up to 15 minutes after deployment and needs consistent traffic from several locations. Smart Placement is available on all Workers plans. ## When it helps and when it does not | Worker | Effect of Smart Placement | |---|---| | Several sequential queries to one database or API in one region | Usually faster: many short round trips replace many long ones | | Answers from request data alone, such as a country redirect | Nothing to gain; there is no backend to move toward | | Calls back ends spread across many regions or replicated | Little gain; there is no single place to move toward | | Serves only static assets | Not affected; assets are served from the location nearest the request | ## Limits of the feature - Only **`fetch` handlers** are placed. RPC methods and named entrypoints are not affected, and a Worker without a `fetch` handler is ignored. - It only considers **locations where the Worker has already run**; it cannot pick a data center that never receives the Worker's traffic. - Assets fetched through the static assets binding are served from wherever the Worker is running, so a placed Worker reads them from its new location. - A Worker can set only one placement option: `mode`, `region`, `host` or `hostname`. The last three are explicit hints that name a cloud region, a TCP host or an HTTP hostname for Cloudflare to run near; use them when the backend's location is known and single-homed. A common shape is to split a Worker in two: an edge Worker that does authentication close to the user and a placed back-end Worker that does the data work, joined by a service binding. ## Checking that it worked - **Placement status** in the Workers API: absent before analysis, `SUCCESS` once the Worker is being optimised, `INSUFFICIENT_INVOCATIONS` when there were not enough requests from enough locations, and the rare `UNSUPPORTED_APPLICATION` when placement made the Worker slower and was reverted. - **The `cf-placement` header** on requests: `remote-LHR` means the request was forwarded and ran near London; `local-EWR` means it ran in the default location near Newark. The documentation warns the header may be removed before Smart Placement exits beta, so do not build logic on it. - **Request duration analytics**, available for Workers with Smart Placement enabled, show whether visitors actually got faster responses.

  • Why would a Worker's placement status stay at INSUFFICIENT_INVOCATIONS?
    Smart Placement needs consistent traffic from multiple locations before it can compare request durations. A Worker with little traffic, or traffic from a single region, never gives it enough samples, so it keeps running in the default location nearest each request.
  • Does Smart Placement move a Worker's RPC methods closer to its database?
    No. Smart Placement only affects `fetch` handlers; RPC methods and named entrypoints are not placed by it. The placement documentation's pattern for that case is a separate back-end Worker with an explicit placement hint, called from an edge Worker over a service binding.

Instead of phoning a distant office ten times to assemble an answer, you fly there once, ask all ten questions in the room, and send back one reply. It only pays when there are many questions for that one office.

  • Smart Placement moves the Worker closer to the visitor.
  • Smart Placement speeds up every Worker, even ones that call no backend.
  • Smart Placement can run a Worker in a location where it never ran.
  • Smart Placement also relocates RPC methods and named entrypoints.
  • Placement takes effect on the first request after the deploy.