hyperledger/fabric · error

ErrAppChannelsAlreadyExists

ErrAppChannelsAlreadyExists

Error message

application channels already exist

What it means

ErrAppChannelsAlreadyExists is returned when a client tries to join a (non-existent) system channel while application channels are already joined on the orderer. Mixing system-channel bootstrap with existing app channels is forbidden; the REST handler maps it to 403 Forbidden.

Source

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

package types

import "github.com/pkg/errors"

// ErrSystemChannelExists is returned when trying to join or remove an application channel when the system channel exists.
//
// 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. Do not join a system channel; it is deprecated — join application channels directly instead
2. If a system channel must exist (legacy), start from a clean orderer (no app channels) and bootstrap the system channel via orderer genesis, not osnadmin
3. Remove/re-provision the orderer for a consistent deployment model

Example fix

// before
osnadmin channel join --channelID test-system-channel --config-block sys.block  # 403
// after
osnadmin channel join --channelID mychannel --config-block app.block  # join app channels only

if errors.Is(err, types.ErrAppChannelsAlreadyExists) {
    // cannot join a system channel once app channels exist; abort legacy flow
}

When it happens

Trigger: POST /participation/v1/channels for a system-channel config block when the orderer already has application channels joined and no system channel exists.

Common situations: During migration, operators attempt to re-establish a deprecated system channel after app channels have already been created via channel participation.

Related errors

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

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