lightning-dev-forget-channel -- Command to remove the DB entries from the database after a close


(WARNING: For advanced users only)

dev-forget-channel id [short_channel_id] [channel_id] [force]


Never use any dev command, including this one, unless you know exactly what you are doing; and have checked with a developer that your understanding is correct. They are meant only as a means of last resort and have the potential to mess things up. You have been warned❗️

The dev-forget-channel forgets the channel with given details. It will perform additional checks on whether it is safe to forget the channel, and only then remove the channel from the DB. Notice that this command is only available if CLN was started with --developer.

Also see

  • id (pubkey): The peer id of the channel to be forgotten. Checks if the channel is still active by checking its funding transaction.
  • short_channel_id (short_channel_id, optional): The short channel id of the channel you want to remove.
  • channel_id (hash, optional): The channel id of the channel you want to remove.
  • force (boolean, optional): Ignores UTXO check for forced removal. The default is False.


On success, an object is returned, containing:

  • forced (boolean): If the command was forced or not.
  • funding_unspent (boolean): The funding is spent or not in the channel.
  • funding_txid (txid): The id of the funding transaction.


The following errors may be reported:

  • -32602: If the given parameters are missing or wrong.
  • -1: Catch all nonspecific errors, eg. Multiple channels: please specify short_channel_id. OR No channels matching that peer_id and that short_channel_id., etc.


Rusty Russell <[email protected]> is mainly responsible.


lightning-close(7), lightning-listchannels(7), lightning-listpeerchannels(7), lightning-listfunds(7)


Main web site:


Example 1: Forget a channel by peer pubkey when only one channel exists with the peer.


lightning-cli dev-forget-channel -k "id"="023d28435ce4b49f068c964aacbcb6dd114317a70f03e5a731ea72d25df1cff35b"
  "id": "example:dev-forget-channel#1",
  "method": "dev-forget-channel",
  "params": {
    "id": "023d28435ce4b49f068c964aacbcb6dd114317a70f03e5a731ea72d25df1cff35b"
  "test": "test"


  "forced": false,
  "funding_unspent": true,
  "funding_txid": "g6efdfb11bee25aa8b2249055a4162e4bd5fa9134bc865c3f054ca666d7ab744"

Example 2: Forget a channel by short channel id when peer has multiple channels.


lightning-cli dev-forget-channel -k "id"="0348e58210bbc128b1cc3cc1a520a654aaa01e5fe65c65341e21b61a1f09da94d5" "short_channel_id"="337x1x0" "force"=True
  "id": "example:dev-forget-channel#2",
  "method": "dev-forget-channel",
  "params": {
    "id": "0348e58210bbc128b1cc3cc1a520a654aaa01e5fe65c65341e21b61a1f09da94d5",
    "short_channel_id": "337x1x0",
    "force": true


  "forced": true,
  "funding_unspent": true,
  "funding_txid": "b254f30a58adde9326b7e8a701f9d5b3c4db2160b58c5378afbe04448018ec8a"