What causes "the local MSP must have an ID" in hyperledger/fabric?

Set the env var: export CORE_PEER_LOCALMSPID=Org1MSP (matching the MSP ID in the MSP dir's config).

the local MSP must have an ID

Error message

the local MSP must have an ID

What it means

InitCrypto checks that a local MSP ID was supplied before initializing the local MSP. If localMSPID is the empty string (CORE_PEER_LOCALMSPID unset or the corresponding flag empty), it returns this error because the peer cannot know which organization the local MSP represents.

Source

Thrown at internal/peer/common/common.go:183

	if err := subv.Unmarshal(&bccspConfig, opts); err != nil {
		return errors.WithMessage(err, "could not decode peer BCCSP configuration")
	}

	return nil
}

// InitCrypto initializes crypto for this peer
func InitCrypto(mspMgrConfigDir, localMSPID, localMSPType string) error {
	// Check whether msp folder exists
	fi, err := os.Stat(mspMgrConfigDir)
	if err != nil {
		return errors.Errorf("cannot init crypto, specified path \"%s\" does not exist or cannot be accessed: %v", mspMgrConfigDir, err)
	} else if !fi.IsDir() {
		return errors.Errorf("cannot init crypto, specified path \"%s\" is not a directory", mspMgrConfigDir)
	}
	// Check whether localMSPID exists
	if localMSPID == "" {
		return errors.New("the local MSP must have an ID")
	}

	// Init the BCCSP
	bccspConfig := factory.GetDefaultOpts()
	err = InitBCCSPConfig(bccspConfig)
	if err != nil {
		return err
	}

	conf, err := msp.GetLocalMspConfigWithType(mspMgrConfigDir, bccspConfig, localMSPID, localMSPType)
	if err != nil {
		return err
	}
	err = mspmgmt.GetLocalMSP(factory.GetDefault()).Setup(conf)
	if err != nil {
		return errors.WithMessagef(err, "error when setting up MSP of type %s from directory %s", localMSPType, mspMgrConfigDir)
	}

View on GitHub (pinned to 2736b63f8f)

Solutions

Set the env var: export CORE_PEER_LOCALMSPID=Org1MSP (matching the MSP ID in the MSP dir's config).
Or set peer.localMSPId in core.yaml / FABRIC_CFG_PATH's peer.yaml.
Confirm the value matches the id inside $CORE_PEER_MSPCONFIGPATH/config.yaml / the MSP's metadata, not just any string.
In Docker Compose, add CORE_PEER_LOCALMSPID to the peer service's environment block.

Example fix

// before (docker-compose peer env missing)
environment:
  - CORE_PEER_MSPCONFIGPATH=/etc/hyperledger/fabric/msp

// after
environment:
  - CORE_PEER_MSPCONFIGPATH=/etc/hyperledger/fabric/msp
  - CORE_PEER_LOCALMSPID=Org1MSP

Defensive patterns

Strategy: validation

Validate before calling

localMSPID := os.Getenv("CORE_PEER_LOCALMSPID")
if localMSPID == "" {
	return errors.New("CORE_PEER_LOCALMSPID must be set (e.g. Org1MSP) before starting the peer")
}

Try / catch

if err := common.InitCrypto(mspDir, localMSPID, localMSPType); err != nil {
	if strings.Contains(err.Error(), "the local MSP must have an ID") {
		return fmt.Errorf("set CORE_PEER_LOCALMSPID or peer.localMSPId in core.yaml: %w", err)
	}
	return err
}

Prevention

Always define CORE_PEER_LOCALMSPID in peer container environments and docker-compose templates.
Keep peer.localMSPId in core.yaml as a fallback so env loss doesn't break startup.
Assert the MSP ID in entrypoint scripts and fail fast with a clear message.
Match the ID exactly to the MSP defined in the channel/org configuration.

When it happens

Trigger: Calling InitCrypto (via peer InitCmd) with localMSPID == "" — typically CORE_PEER_LOCALMSPID not set in the environment and not provided via flags/config while starting or operating the peer.

Common situations: Running the peer container without -e CORE_PEER_LOCALMSPID=Org1MSP; clearing core.yaml's peer.localMSPId during customization; scripted environments losing the env var across sudo/su; joining an org with a renamed MSP ID but not updating the peer config.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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