hyperledger/fabric · warning

ErrChannelPendingRemoval

ErrChannelPendingRemoval

Error message

channel pending removal

What it means

ErrChannelPendingRemoval is returned when joining, updating, fetching, or removing a channel that is currently in the process of being removed. The removal is asynchronous; the channel is in a transient 'removing' state and further operations are rejected with HTTP 409 Conflict.

Source

Thrown at orderer/common/types/errors.go:31

// Deprecated: system channel no longer supported
var ErrSystemChannelExists = errors.New("system channel exists")

// ErrSystemChannelNotSupported is returned when trying to join with a system channel config block.
var ErrSystemChannelNotSupported = errors.New("system channel not supported")

// ErrChannelAlreadyExists is returned when trying to join a app channel that already exists (when the system channel does not
// exist), or when trying to join the system channel when it already exists.
var ErrChannelAlreadyExists = errors.New("channel already exists")

// ErrAppChannelsAlreadyExists is returned when trying to join a system channel (that does not exist) when application channels
// already exist.
var ErrAppChannelsAlreadyExists = errors.New("application channels already exist")

// ErrChannelNotExist is returned when trying to remove or list a channel that does not exist
var ErrChannelNotExist = errors.New("channel does not exist")

// ErrChannelPendingRemoval is returned when trying to remove or list a channel that is being removed.
var ErrChannelPendingRemoval = errors.New("channel pending removal")

// ErrChannelRemovalFailure is returned when a removal attempt failure has been recorded.
var ErrChannelRemovalFailure = errors.New("channel removal failure")

// ErrChannelNotReady is returned when trying to update a channel that is a follower
var ErrChannelNotReady = errors.New("channel is not ready, he is a follower")

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Poll 'osnadmin channel list' until the channel disappears, then perform the join/update
2. Retry the operation after a delay (removal is transient)
3. Check removal status: the REST API reports channel status (removing) — wait for it to clear
4. Serialize automation so join/update commands never run concurrently with removal

Example fix

// before
osnadmin channel remove --channelID mychannel
osnadmin channel join --channelID mychannel --config-block app.block  # 409 pending removal
// after
osnadmin channel remove --channelID mychannel
until ! osnadmin channel list | grep -q mychannel; do sleep 2; done
osnadmin channel join --channelID mychannel --config-block app.block

if errors.Is(err, types.ErrChannelPendingRemoval) {
    time.Sleep(2 * time.Second)
    // retry join/update, or wait until channel disappears from list
}

When it happens

Trigger: POST (join) or PUT (update) to /participation/v1/channels/<id> while a prior DELETE for that channel is still completing; FetchBlock/JoinChannel racing with an in-flight removal.

Common situations: Scripts that DELETE and immediately re-JOIN a channel without waiting for removal to finish; concurrent operators acting on the same channel; retries hitting a channel mid-removal.

Related errors

• empty block data
• failed extracting envelope from block
• the block isn't a system channel block because it lacks Cons
• ErrSystemChannelExists
• ErrSystemChannelNotSupported

AI-assisted analysis of hyperledger/fabric@2736b63f8f (2026-09-04). Data as JSON: /api/errors/b29b57c60d6dafe2. Report an issue: GitHub.