# subname.remove

> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).

Removes a subname. Parameters, return value, errors and examples for subname.remove in @ensforge/sdk. Options, result, errors and examples for subname.remove.

Source: https://ensforge.com/docs/reference/sdk/subname/remove

<ApiMeta kind="Write" stability="stable" since="1.0.0" source="packages/sdk/src/actions/subname/remove/index.ts#L64" />

Removes a subname. Resolves once the transaction is submitted.

## When to use [#when-to-use]

Use to take back a name you gave out, or to drop your own subname. Use [`removeSync`](/docs/reference/sdk/subname/remove#wait-for-the-receipt-with-removesync) to wait for the receipt.

## Details [#details]

- ENSv2: `unregister` in the parent's subregistry, which also clears the child's resolver and
  subregistry so nothing carries over to a later owner.
- ENSv1: owner and resolver are set to zero, from the parent when the signer owns it or is
  its operator, otherwise as the child's owner. Under an unwrapped parent the registry clears a wrapped
  child, which unwraps it.

<Callout type="warn" title="Gotchas">
- Emancipated children (ENSv1 `parentCannotControl`, or an emancipated ENSv2 subregistry)
  cannot be removed by their parent.
</Callout>

## Signature [#signature]

```ts
function remove(
  client: Like,
  options: remove.Options & Write.Options,
): Promise<remove.ReturnType>
```

Call it as `ens.subname.remove(options)` on a client, or `Actions.subname.remove(client, options)`.

## Parameters [#parameters]

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` |  | Full name of the child. Normalized automatically. |

Also takes the [write options](/docs/reference/sdk/client#write-options).

## Returns [#returns]

Resolves to `Write.Result`. Submitted transaction hashes and the plan that produced them.

| Field | Type | Description |
| --- | --- | --- |
| `hash` | `Hex` | Hash of the last transaction. |
| `hashes` | `readonly Hex[]` | Every submitted transaction, in order. |
| `id` | `string` | EIP-5792 bundle id when the calls were sent as one batch. |
| `plan` | `Plan` | The plan the write executed: its steps, in order, as they were submitted. |

## Errors [#errors]

| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) | invalid input. |
| [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_NOT_REGISTERED`](/docs/reference/errors/NAME_NOT_REGISTERED), [`NAME_EXPIRED`](/docs/reference/errors/NAME_EXPIRED) | the child or parent does not exist. |
| [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_RESERVED`](/docs/reference/errors/NAME_RESERVED), [`NAME_UNREACHABLE`](/docs/reference/errors/NAME_UNREACHABLE) | the parent is reserved or ENSv2 resolution no longer reaches it. |
| [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES), [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER), [`FUSE_BURNED`](/docs/reference/errors/FUSE_BURNED) | the account may not remove it. |
| [`ConfigError`](/docs/reference/errors/config-error) | [`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED) | no signing account is known. |
| [`UserRejectedError`](/docs/reference/errors/user-rejected-error) | [`USER_REJECTED`](/docs/reference/errors/USER_REJECTED) | the user rejects the request. |
| [`WalletError`](/docs/reference/errors/wallet-error) | [`CHAIN_MISMATCH`](/docs/reference/errors/CHAIN_MISMATCH), [`ACCOUNT_NOT_FOUND`](/docs/reference/errors/ACCOUNT_NOT_FOUND) | the wallet is on another chain or has no account to sign with. |
| [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`WALLET_BATCH_UNSUPPORTED`](/docs/reference/errors/WALLET_BATCH_UNSUPPORTED) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |

It can also fail with the errors every write can (`Errors.WriteError`: the common errors plus `InsufficientFundsError`, `TransactionError`, `UnsupportedError`, `UserRejectedError`, `WalletError`).

See [How errors work](/docs/sdk/errors-explained).

## Examples [#examples]

<Tabs groupId="api" items={["Client","Standalone","Effect"]} persist>
<Tab>
```ts title="Removing a subname"
const { hash } = await ens.subname.remove({ name: "pay.alice.eth" })
```
</Tab>

<Tab>
```ts title="Removing a subname with a standalone call"
import { Actions } from "@ensforge/sdk"

await Actions.subname.remove(ens, { name: "pay.alice.eth" })
```
</Tab>

<Tab>
```ts title="Removing a subname in an Effect program"
import { Actions } from "@ensforge/sdk/effect"

yield* Actions.subname.remove(ens, { name: "pay.alice.eth" })
```
</Tab>
</Tabs>

## Plan methods [#plan-methods]

Each method takes the same options as `subname.remove` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending).

| Method | Description |
| --- | --- |
| `subname.remove.prepare(options)` | Builds the plan without sending anything. |
| `subname.remove.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. |
| `subname.remove.estimateGas(options)` | Estimates the gas and ETH the plan needs. |

## Wait for the receipt with `removeSync` [#wait-for-the-receipt-with-removesync]

Removes a subname. Resolves once the receipt is in.

Use when the next step depends on the change being on-chain.

`subname.removeSync` takes the same options plus [`confirmations` and `timeout`](/docs/reference/sdk/client#sync-options).

Resolves to `Write.SyncResult`. Receipts plus the submitted hashes and plan.

<Tabs groupId="api" items={["Client","Standalone","Effect"]} persist>
<Tab>
```ts title="Removing a subname and waiting"
const { receipt } = await ens.subname.removeSync({ name: "pay.alice.eth" })
```
</Tab>

<Tab>
```ts title="Waiting with a standalone call"
import { Actions } from "@ensforge/sdk"

await Actions.subname.removeSync(ens, { name: "pay.alice.eth" })
```
</Tab>

<Tab>
```ts title="Waiting in an Effect program"
import { Actions } from "@ensforge/sdk/effect"

yield* Actions.subname.removeSync(ens, { name: "pay.alice.eth" })
```
</Tab>
</Tabs>

## See also [#see-also]

- [`subname.create`](/docs/reference/sdk/subname/create) to create it again