What causes "expecting one CID argument" in ipfs/kubo?

Pass exactly one CID/path: `ipfs pin remote add --service= `.

expecting one CID argument

Error message

expecting one CID argument

What it means

`ipfs pin remote add` requires exactly one positional argument: the CID (or path) to pin on the remote service. The pre-run handler rejects any other argument count with this error, since the remote pin request is defined by a single target.

Source

Thrown at core/commands/pin/remotepin.go:160

	Type: RemotePinOutput{},
	Run: func(req *cmds.Request, res cmds.ResponseEmitter, env cmds.Environment) error {
		ctx, cancel := context.WithCancel(req.Context)
		defer cancel()

		enc, err := cmdenv.GetCidEncoder(req)
		if err != nil {
			return err
		}

		// Get remote service
		c, err := getRemotePinServiceFromRequest(req, env)
		if err != nil {
			return err
		}

		// Prepare value for Pin.cid
		if len(req.Arguments) != 1 {
			return fmt.Errorf("expecting one CID argument")
		}
		api, err := cmdenv.GetApi(env, req)
		if err != nil {
			return err
		}
		p, err := cmdutils.PathOrCidPath(req.Arguments[0])
		if err != nil {
			return err
		}

		rp, _, err := api.ResolvePath(ctx, p)
		if err != nil {
			return err
		}

		// Prepare Pin.name
		opts := []pinclient.AddOption{}
		if name, nameFound := req.Options[pinNameOptionName]; nameFound {

View on GitHub (pinned to 329838acdf)

Solutions

Pass exactly one CID/path: `ipfs pin remote add --service=<svc> <cid>`.
Loop over CIDs in the script, calling `pin remote add` once per CID.
Guard for an empty CID variable before invoking the command.
Remember to pass `--service` (and `--bg`/`--name` as needed) as options, not as positional arguments.

Example fix

// before (batch attempt)
exec.Command("ipfs", "pin", "remote", "add", "--service", "pinata", cid1, cid2).Run()
// after
for _, cid := range []string{cid1, cid2} {
  exec.Command("ipfs", "pin", "remote", "add", "--service", "pinata", cid).Run()
}

Defensive patterns

Strategy: validation

Validate before calling

if len(cids) != 1 {
    return fmt.Errorf("pin remote add takes exactly one CID, got %d", len(cids))
}
if cids[0] == "" {
    return errors.New("CID argument is empty")
}

Prevention

Loop per-CID instead of batching arguments
Validate CID variables are non-empty before the call
Pass service/background as options, never as positional args

When it happens

Trigger: `ipfs pin remote add` with zero arguments (forgot the CID) or with multiple CIDs (batching is not supported by this command); RPC `pin/remote/add` calls with an empty or multi-element Arguments array.

Common situations: Scripts iterating over CID lists and passing them all in one call; forgetting the CID because service name/background flags were the focus; variable holding the CID is empty.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/77b51b22fb611e03. Report an issue: GitHub.