hyperledger/fabric · error

ErrSystemChannelExists

ErrSystemChannelExists

Error message

system channel exists

What it means

ErrSystemChannelExists is returned when a client tries to join or remove an application channel while a system channel still exists on the orderer. With a system channel present, only GET operations are allowed on application channels, so the REST handler maps this to 405 Method Not Allowed.

Source

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

/*
Copyright IBM Corp. All Rights Reserved.

SPDX-License-Identifier: Apache-2.0
*/

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")

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Remove the system channel ('osnadmin channel remove' on the system channel, or rebootstrap without systemChannel) then join app channels
2. Upgrade to Fabric where the system channel is deprecated/removed and re-bootstrap the orderer without a system channel genesis block
3. While the system channel exists, manage app channels only via the legacy chain creation flow; GET is allowed to list channels

Example fix

// before
osnadmin channel join --channelID mychannel --config-block app.block  # 405: system channel exists
// after
osnadmin channel remove --channelID test-system-channel  # remove system channel first
osnadmin channel join --channelID mychannel --config-block app.block

resp, err := client.JoinChannel(cfg)
if errors.Is(err, types.ErrSystemChannelExists) {
    // only GET allowed; remove the system channel first
}

When it happens

Trigger: POST /participation/v1/channels (join) or DELETE (remove) for an app channel while the orderer is bootstrapped with a system channel; also surfaced via sendJoinError and sendUpdateError.

Common situations: Upgrading from a 2.x deployment bootstrapped with a system channel and trying to manage app channels with osnadmin; forgetting to remove the system channel before using channel participation.

Related errors

• the block isn't a system channel block because it lacks Cons
• ErrSystemChannelNotSupported
• ErrChannelAlreadyExists
• ErrAppChannelsAlreadyExists
• empty block data

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