spawn()

protected spawn<T>(namespace, name?): Promise<ActorStub & PublicMethods<T>>

Create a child instance of an actor binding and return its stub — one worker per job, minted from inside the agent that needs it. The child is a deliberately created instance owned by this agent, not one materialized by addressing a name. It is the same stub binding.idFromName(...) hands back, typed against the bound class, so calling it is ordinary actor RPC:

const child = await this.spawn(this.env.WORKER, `w-${job.id}`);
await child.assign(job); // typed, and dispatched over actor RPC

Omit name and the child gets a fresh, collision-free one; keep the returned stub’s id if you need to reach that child again later. name is a routing name in your own vocabulary — an order id, an E.164 number, an email — and is encoded into an addressable actor id for you, by the same encoder the front door uses, so a name and its child agree on one instance no matter which side minted it. A name with no faithful id (empty, or one that encodes too long to address) is refused here, before anything is created, with a TypeError naming the name and the limit: a child under an unaddressable id would take writes and then fail to come back the first time it is evicted. Room is finite. When this agent is already at its cap the platform refuses, and the refusal arrives as a QuotaExceededError you can catch at this call site — nothing is created when it throws:

try {
  const child = await this.spawn(this.env.WORKER, `w-${job.id}`);
  await child.assign(job);
} catch (err) {
  if (err instanceof QuotaExceededError) return this.shed(job);
  throw err;
}

Added with SDK 0.15 — a new inherited member, so a subclass that already declares spawn must rename it (or align its signature to override this method). Type Parameters

Type Parameter
`T` extends `StatefulActor`<`Env`>

Parameters

Parameter	Type	Description
`namespace`	`ActorNamespace`<`T`>	The actor binding to create the child in — `this.env.<BINDING>`.
`name?`	`string`	The child’s routing name. Defaults to a fresh unique name.

Returns Promise<ActorStub & PublicMethods<T>> The child’s stub, typed against the bound actor class. Throws TypeError when name has no addressable actor id, or when the binding cannot create instances. Throws QuotaExceededError when creating the child would exceed a limit already reached.

QuotaExceededError

Thrown when the platform refuses to create a new actor instance because a limit is already reached — the parent’s cap on how many children it may hold, or an account-wide cap on instances. It is an ordinary application error, raised at the call site that asked for the instance, so it can be caught, logged, and reported like any other:

try {
  const worker = await this.spawn(this.env.WORKER, `w-${job.id}`);
  await worker.assign(job);
} catch (err) {
  if (err instanceof QuotaExceededError) {
    // Out of room — shed the job rather than failing the whole batch.
    await this.schedule(60, "retryLater", job);
    return;
  }
  throw err;
}

Match it with instanceof, or with err.name === "QuotaExceededError" where the error crossed a boundary that rebuilt it from its name. Nothing was created when this is thrown: the refusal happens before the instance exists, so there is no half-made child to clean up. Retrying the same call only succeeds once room is freed. Extends

Error

Constructors

Constructor	Description
constructor	-

Properties

Property	Description
code	The machine-readable code from the refusal, when it carried one.
detail	The human-readable detail from the refusal, when it carried one.
status	The HTTP status the refusal arrived with.

constructor

new QuotaExceededError(args): QuotaExceededError

Parameters

Parameter	Type	Description
`args`	{ `code?`: `string`; `detail?`: `string`; `status`: `number`; }	`status` is the HTTP status of the refusal; `code` and `detail` are the machine-readable code and human-readable text it carried, either of which may be absent.
`args.code?`	`string`	-
`args.detail?`	`string`	-
`args.status`	`number`	-

Returns QuotaExceededError Overrides Error.constructor

code

readonly code: string | undefined

The machine-readable code from the refusal, when it carried one.

detail

readonly detail: string | undefined

The human-readable detail from the refusal, when it carried one.

status

readonly status: number

The HTTP status the refusal arrived with.

Get Started

Inside the Managed Harness

The Agent Harness SDK

The Agent Runtime SDK

The Agent Client SDK

For AI Agents

QuotaExceededError

constructor

code

detail

status

​QuotaExceededError

​constructor

​code

​detail

​status

QuotaExceededError

constructor

code

detail

status