hyperledger/fabric · error

Bad configuration envelope: %s

Error message

Bad configuration envelope: %s

What it means

This error is thrown by cscc (the system chaincode that handles channel creation/joining) in validateConfigBlock when protoutil.UnmarshalEnvelopeOfType cannot decode the submitted config transaction envelope as a common.HeaderType_CONFIG envelope. It means the envelope submitted to JoinChain was not a marshaled ConfigEnvelope (e.g. it is a different header type, malformed protobuf bytes, or wrapped incorrectly). The %s carries the underlying unmarshal error.

Source

Thrown at core/scc/cscc/configure.go:225

		}

		return e.getChannels()

	}
	return shim.Error(fmt.Sprintf("Requested function %s not found.", fname))
}

// validateConfigBlock validate configuration block to see whenever it's contains valid config transaction
func validateConfigBlock(block *common.Block, bccsp bccsp.BCCSP) error {
	envelopeConfig, err := protoutil.ExtractEnvelope(block, 0)
	if err != nil {
		return errors.Errorf("Failed to %s", err)
	}

	configEnv := &common.ConfigEnvelope{}
	_, err = protoutil.UnmarshalEnvelopeOfType(envelopeConfig, common.HeaderType_CONFIG, configEnv)
	if err != nil {
		return errors.Errorf("Bad configuration envelope: %s", err)
	}

	if configEnv.Config == nil {
		return errors.New("Nil config envelope Config")
	}

	if configEnv.Config.ChannelGroup == nil {
		return errors.New("Nil channel group")
	}

	if configEnv.Config.ChannelGroup.Groups == nil {
		return errors.New("No channel configuration groups are available")
	}

	_, exists := configEnv.Config.ChannelGroup.Groups[channelconfig.ApplicationGroupKey]
	if !exists {
		return errors.Errorf("Invalid configuration block, missing %s "+
			"configuration group", channelconfig.ApplicationGroupKey)

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Regenerate the config envelope using the standard path: cryptogen/configtxgen to produce a genesis block, or `configtxlator proto_encode --type common.ConfigEnvelope` for updates
2. Ensure the envelope passed to JoinChain is the full ConfigEnvelope (not a ConfigUpdateEnvelope) marshaled into a HeaderType_CONFIG envelope
3. Verify the envelope bytes are not corrupted in transit (compare sha256 of the marshaled envelope on both sides)
4. Check that protoutil.CreateSignedEnvelope with common.HeaderType_CONFIG was used and signatures applied with the right MSP identities

Example fix

// before: raw ConfigEnvelope passed to JoinChain
env := &common.ConfigEnvelope{Config: cfg}
payload, _ := proto.Marshal(env)
// after: wrap in an envelope of HeaderType_CONFIG
envBytes, _ := proto.Marshal(env)
env2, _ := protoutil.CreateSignedEnvelope(common.HeaderType_CONFIG, chID, signer, &common.ConfigEnvelope{}, 0, 0)

env, err := protoutil.UnmarshalEnvelopeOfType(envelopeConfig, common.HeaderType_CONFIG, &common.ConfigEnvelope{})
if err != nil { return fmt.Errorf("config envelope not decodable: %w", err) }

func isConfigEnvelope(env *common.Envelope) bool {
    p := &common.Payload{}
    if protoutil.Unmarshal(env.Payload, p) != nil { return false }
    return p.Header != nil && p.Header.ChannelHeader != nil &&
        common.HeaderType(p.Header.ChannelHeader.Type) == common.HeaderType_CONFIG
}

if err != nil {
    var ce *common.ConfigEnvelope
    if _, uerr := protoutil.UnmarshalEnvelopeOfType(envelopeConfig, common.HeaderType_CONFIG, ce); uerr != nil {
        return fmt.Errorf("submit a valid HeaderType_CONFIG envelope: %w", uerr)
    }
}

When it happens

Trigger: Calling cscc.Invoke (JoinChain) with an envelope whose payload is not a marshaled ConfigEnvelope; submitting the genesis/config envelope for the wrong header type (e.g. HeaderType_MESSAGE or HeaderType_ENDORSER_TRANSACTION); passing corrupted or truncated envelope bytes; wrapping the ConfigEnvelope in an extra serialization layer before signing.

Common situations: Fabric SDK channel-creation flows where the user concatenates or re-marshals envelopes incorrectly; custom tooling that builds config transactions by hand; upgrading Fabric versions where the config envelope schema changed; submitting an update envelope (HeaderType_CONFIG_UPDATE) where a fully-applied config envelope was expected.

Related errors

• Nil config envelope Config
• error unmarshalling
• error encoding output
• error unmarshalling original config
• error unmarshalling updated config

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