'%s' command can only be executed against one peer. received

Error message

'%s' command can only be executed against one peer. received %d

What it means

This error is returned by validatePeerConnectionParameters when more than one peer address was supplied for a CLI command that only supports a single peer. Only the 'invoke' command is allowed to target multiple peers (for multi-endorsement); all other commands (query, install, instantiate, etc.) must be executed against exactly one peer.

Source

Thrown at internal/peer/chaincode/common.go:340

				if peerChannelConfig.EndorsingPeer {
					peerConfig, ok := networkConfig.Peers[peer]
					if !ok {
						return errors.Errorf("peer '%s' is defined in the channel config but doesn't have associated peer config", peer)
					}
					peerAddresses = append(peerAddresses, peerConfig.URL)
					tlsRootCertFiles = append(tlsRootCertFiles, peerConfig.TLSCACerts.Path)
				}
			}
		}
	}

	// currently only support multiple peer addresses for invoke
	multiplePeersAllowed := map[string]bool{
		"invoke": true,
	}
	_, ok := multiplePeersAllowed[cmdName]
	if !ok && len(peerAddresses) > 1 {
		return errors.Errorf("'%s' command can only be executed against one peer. received %d", cmdName, len(peerAddresses))
	}

	if len(tlsRootCertFiles) > len(peerAddresses) {
		logger.Warningf("received more TLS root cert files (%d) than peer addresses (%d)", len(tlsRootCertFiles), len(peerAddresses))
	}

	if viper.GetBool("peer.tls.enabled") {
		if len(tlsRootCertFiles) != len(peerAddresses) {
			return errors.Errorf("number of peer addresses (%d) does not match the number of TLS root cert files (%d)", len(peerAddresses), len(tlsRootCertFiles))
		}
	} else {
		tlsRootCertFiles = nil
	}

	return nil
}

// ChaincodeCmdFactory holds the clients used by ChaincodeCmd

View on GitHub (pinned to 2736b63f8f)

Solutions

Keep only one --peerAddresses flag for non-invoke commands
Use the command with multiple peers only with 'invoke'
If multiple endorsements are needed, use invoke with the required endorsement policy
Fix scripts to pass a single peer for query/lifecycle subcommands

Example fix

// before
peer chaincode query -C mychannel -n mycc -c '{"Args":["Query"]}' --peerAddresses peer0.org1:7051 --peerAddresses peer0.org2:7051
// after
peer chaincode query -C mychannel -n mycc -c '{"Args":["Query"]}' --peerAddresses peer0.org1:7051

Defensive patterns

Strategy: validation

Validate before calling

NADDR=$(grep -o -- '--peerAddresses' <<<"$CMD" | wc -l); [[ "$SUBCMD" == "invoke" || $NADDR -le 1 ]] || { echo "$SUBCMD supports at most one peer"; exit 1; }

Prevention

Only pass multiple --peerAddresses flags to invoke
Build command flags conditionally per subcommand in scripts
Use invoke for multi-endorsement scenarios, query for single-peer reads
Lint CLI wrappers to reject repeated --peerAddresses on non-invoke subcommands

When it happens

Trigger: Running e.g. 'peer chaincode query' with --peerAddresses given twice (or with peers resolved from channel config producing multiple addresses), where cmdName is not 'invoke'.

Common situations: Copy-pasting an invoke command's multiple --peerAddresses flags into a query or lifecycle command, scripting that appends all channel peers regardless of the subcommand being run.

Related errors

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