What causes "error parsing transient string" in hyperledger/fabric?

Pass valid JSON: `--transient '{"secretKey":" "}'` with proper shell quoting

error parsing transient string

Error message

error parsing transient string

What it means

The --transient flag must be valid JSON mapping strings to base64-encoded byte values. ChaincodeInvokeOrQuery unmarshals it before creating the proposal; a malformed value produces this wrapped error.

Source

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

) (*pb.ProposalResponse, error) {
	// Build the ChaincodeInvocationSpec message
	invocation := &pb.ChaincodeInvocationSpec{ChaincodeSpec: spec}

	creator, err := signer.Serialize()
	if err != nil {
		return nil, errors.WithMessage(err, "error serializing identity")
	}

	funcName := "invoke"
	if !invoke {
		funcName = "query"
	}

	// extract the transient field if it exists
	var tMap map[string][]byte
	if transient != "" {
		if err := json.Unmarshal([]byte(transient), &tMap); err != nil {
			return nil, errors.Wrap(err, "error parsing transient string")
		}
	}

	prop, txid, err := protoutil.CreateChaincodeProposalWithTxIDAndTransient(pcommon.HeaderType_ENDORSER_TRANSACTION, cID, invocation, creator, txID, tMap)
	if err != nil {
		return nil, errors.WithMessagef(err, "error creating proposal for %s", funcName)
	}

	signedProp, err := protoutil.GetSignedProposal(prop, signer)
	if err != nil {
		return nil, errors.WithMessagef(err, "error creating signed proposal for %s", funcName)
	}

	responses, err := processProposals(endorserClients, signedProp)
	if err != nil {
		return nil, errors.WithMessagef(err, "error endorsing %s", funcName)
	}

View on GitHub (pinned to 2736b63f8f)

Solutions

Pass valid JSON: `--transient '{"secretKey":"<base64value>"}'` with proper shell quoting
Base64-encode each value: `echo -n 'mysecret' | base64` then embed the result
On Windows, use double quotes escaped appropriately or set the value via a script instead of inline

Example fix

// before
--transient secret=mysecret
// after
--transient '{"secret":"bXlzZWNyZXQ="}'

Defensive patterns

Strategy: validation

Validate before calling

func validateTransient(s string) error {
    if s == "" { return nil }
    var m map[string][]byte
    if err := json.Unmarshal([]byte(s), &m); err != nil {
        return fmt.Errorf("transient must be JSON map[string]string(base64): %w", err)
    }
    return nil
}

Try / catch

if strings.Contains(err.Error(), "error parsing transient string") {
    fmt.Println("Fix --transient to be valid JSON like '{\"key\":\"<base64>\"}' and check shell quoting")
}

Prevention

Build transient maps programmatically with json.Marshal instead of hand-written strings
Base64-encode values before embedding
Test quoting on the target shell (PowerShell/cmd escaping differs from bash)

When it happens

Trigger: Passing `--transient` with non-JSON content (e.g. `--transient key=value` instead of `{"key":"..."}`), single quotes inside the value on Windows shells, or unquoted JSON consumed by the shell.

Common situations: Shell quoting issues (curl-style habits, PowerShell escaping), forgetting base64 encoding of values, passing plain key=value syntax from other frameworks.

Related errors

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