What causes "trailing args detected" in hyperledger/fabric?

Remove all positional arguments: run exactly `peer node start`.

trailing args detected

Error message

trailing args detected

What it means

`peer node start` accepts no positional arguments; if any trailing args are passed to the command, RunE immediately fails with this fmt.Errorf before starting the server. It is a strict CLI argument guard, not a runtime condition.

Source

Thrown at internal/peer/node/start.go:128

	defaultChaincodePort   = 7052
)

var chaincodeDevMode bool

func startCmd() *cobra.Command {
	// Set the flags on the node start command.
	flags := nodeStartCmd.Flags()
	flags.BoolVarP(&chaincodeDevMode, "peer-chaincodedev", "", false, "start peer in chaincode development mode")
	return nodeStartCmd
}

var nodeStartCmd = &cobra.Command{
	Use:   "start",
	Short: "Starts the node.",
	Long:  `Starts a node that interacts with the network.`,
	RunE: func(cmd *cobra.Command, args []string) error {
		if len(args) != 0 {
			return fmt.Errorf("trailing args detected")
		}
		// Parsing of the command line is done so silence cmd usage
		cmd.SilenceUsage = true
		return serve(args)
	},
}

// externalVMAdapter adapts coerces the result of Build to the
// container.Interface type expected by the VM interface.
type externalVMAdapter struct {
	detector *externalbuilder.Detector
}

func (e externalVMAdapter) Build(
	ccid string,
	mdBytes []byte,
	codePackage io.Reader,
) (container.Instance, error) {

View on GitHub (pinned to 2736b63f8f)

Solutions

Remove all positional arguments: run exactly `peer node start`.
Pass configuration via flags/env (CORE_PEER_* variables, -f for a serve config) instead of positional args.
Fix the calling script so it does not append stray parameters to the command.

Example fix

// before
peer node start peer1
// after
peer node start

Defensive patterns

Strategy: validation

Validate before calling

if [ "$#" -ne 0 ]; then echo "usage: peer node start (no args)" >&2; exit 1; fi
peer node start

Try / catch

if err := cmd.Run(); err != nil && strings.Contains(err.Error(), "trailing args detected") {
    return fmt.Errorf("peer node start takes no positional arguments")
}

Prevention

Run `peer node start` with exactly zero positional arguments.
Configure the node via CORE_PEER_* env vars or the -f serve config file.
Quoted/empty shell variables can still become args — audit script expansions.

When it happens

Trigger: Running `peer node start <something>` — any extra positional tokens after `start`.

Common situations: Copy-pasting commands like `peer node start peer1` assuming a node name argument; shell scripts appending unintended arguments; confusing `node start` with other subcommands that take args.

Related errors

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