> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# spawn()

> `protected` **spawn**\<`T`>(`namespace`, `name?`): `Promise`\<[`ActorStub`](/docs/edge-compute/stateful-actors/api-reference/stub) & `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:

```ts theme={null}
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](/docs/agent-sdk/interface/spawn#quotaexceedederror) you can catch at
this call site — nothing is created when it throws:

```ts theme={null}
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`](/docs/edge-compute/stateful-actors/api-reference/base)\<`Env`> |

**Parameters**

| Parameter | Type | Description |
| - | - | - |
| `namespace` | [`ActorNamespace`](/docs/edge-compute/stateful-actors/api-reference/namespace)\<`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`](/docs/edge-compute/stateful-actors/api-reference/stub) & `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](/docs/agent-sdk/interface/spawn#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:

```ts theme={null}
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](/docs/agent-sdk/interface/spawn#quotaexceedederror) | - |

**Properties**

| Property | Description |
| - | - |
| [code](/docs/agent-sdk/interface/spawn#code) | The machine-readable code from the refusal, when it carried one. |
| [detail](/docs/agent-sdk/interface/spawn#detail) | The human-readable detail from the refusal, when it carried one. |
| [status](/docs/agent-sdk/interface/spawn#status) | The HTTP status the refusal arrived with. |

### constructor

> **new QuotaExceededError**(`args`): [`QuotaExceededError`](/docs/agent-sdk/interface/spawn#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`](/docs/agent-sdk/interface/spawn#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.