# this.offload

> Run CPU work in a bounded worker-thread pool so other server calls can keep answering.

Source: https://frontmcp.dev/reference/sdk/offload

[Covers FrontMCP 1.11.0](https://frontmcp.dev/versions#how-pages-are-checked) as of November 4, 2026

A CPU-heavy parser on the server's event loop delays every other call. `this.offload()` runs an exported function in a worker thread. Its arguments and result cross the boundary by structured clone; providers and request objects stay in the server.

```ts
await this.offload({ module: new URL("./parse.js", import.meta.url), export: "parse" }, [input], { budgetMs?, signal? });
```



---

<a id="reference"></a>

## Reference

<a id="thisoffloadmoduleref-args-options"></a>

### `this.offload(moduleRef, args, options?)`

Available on execution contexts. Returns a promise of the function's result.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `moduleRef.module` | `string \| URL` | required | Absolute file path or `file:` URL; package names and relative paths are refused. |
| `moduleRef.export` | `string` | `"default"` | Exported function to call. |
| `args` | `readonly unknown[]` | required | Arguments that structured clone can carry. |
| `options.budgetMs` | `number` | server budget, 30000 ms | Execution deadline; waiting for a worker does not count. Overrun terminates the worker. |
| `options.signal` | `AbortSignal` | `this.signal` | Abort terminates the worker and rejects the call. |

<a id="frontmcp-offload-"></a>

### `@FrontMcp({ offload })`

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `maxWorkers` | `number` | available parallelism minus one, clamped to 1–4 | Maximum workers per scope; excess calls wait. |
| `idleTimeoutMs` | `number` | `30000` | Stop an idle worker after this interval. |
| `budgetMs` | `number` | `30000` | Default execution deadline. |
| `env` | `string[]` | `["NODE_ENV"]` | Environment variables copied into workers. |

Resources and resource templates can set `worker: true` or `worker: { budgetMs }` to run reads in the pool. Jobs choose `runner: "worker"`. These workers cannot resolve the server's providers; pass data to an exported function when it needs provider results. Resource reads receive a request `signal`; a resource's `this.fetch()` does not automatically pass it.

<a id="caveats"></a>

#### Caveats

Node only. Workers start on first use. Functions, live connections and other values that cannot be cloned fail with `OFFLOAD_NOT_CLONEABLE`. A public FrontMCP error keeps its public code and remedy across the boundary; other exceptions remain internal. Worker console output goes to stderr for stdio servers.

<a id="usage"></a>

## Usage

<a id="moving-a-calculation-out-of-a-tool"></a>

### Moving a calculation out of a tool

> **Note**
>
> The Playground's Web Worker cannot start Node worker threads or load an absolute server module. These files are a Node server example; keep the calculation module in the deployed output.

```ts count.ts
export function count(words: string[]) {
  return { words: words.length };
}
```

```ts count.tool.ts
import { Tool, ToolContext, z } from "@frontmcp/sdk";

@Tool({ name: "count_words", inputSchema: { words: z.array(z.string()) } })
export class CountWords extends ToolContext {
  async execute({ words }: { words: string[] }) {
    return this.offload({ module: new URL("./count.js", import.meta.url), export: "count" }, [words]);
  }
}
```

<a id="troubleshooting"></a>

## Troubleshooting

<a id="offloaded--ran-past-its--ms-budget-and-was-stopped"></a>

### `Offloaded "…" ran past its … ms budget and was stopped`

`OFFLOAD_BUDGET_EXCEEDED` means the worker was terminated. Reduce the work or raise `budgetMs`.

<a id="offloaded--was-stopped-its-call-was-cancelled"></a>

### `Offloaded "…" was stopped: its call was cancelled`

`OFFLOAD_ABORTED` means the signal aborted. Shutdown can stop a worker too. Do not retry cancelled work automatically.

<a id="the-worker-running--failed-"></a>

### `The worker running "…" failed: …`

`OFFLOAD_WORKER_FAILED` (`OffloadWorkerError`) means a worker couldn't start (`it could not start: …`), or crashed or exited before it answered. The text after `failed:` says which.

<a id="offload_unsupported_runtime"></a>

### `OFFLOAD_UNSUPPORTED_RUNTIME`

Run this work on Node, or leave the resource's `worker` option off in a browser or edge deployment.