ipfs/kubo · error
a service name must be passed
Error message
a service name must be passed
What it means
`getRemotePinServiceFromRequest` builds a client for a remote pinning service named via the `--service` option. If that option was not supplied on the command invocation (`pin remote ls/add/rm` paths that need the service), it cannot know which service to talk to and returns this error.
Source
Thrown at core/commands/pin/remotepin.go:741
func (l PinServicesList) Len() int {
return len(l.RemoteServices)
}
func (l PinServicesList) Swap(i, j int) {
s := l.RemoteServices
s[i], s[j] = s[j], s[i]
}
func (l PinServicesList) Less(i, j int) bool {
s := l.RemoteServices
return s[i].Service < s[j].Service
}
func getRemotePinServiceFromRequest(req *cmds.Request, env cmds.Environment) (*pinclient.Client, error) {
service, serviceFound := req.Options[pinServiceNameOptionName]
if !serviceFound {
return nil, fmt.Errorf("a service name must be passed")
}
serviceStr := service.(string)
var err error
c, err := getRemotePinService(env, serviceStr)
if err != nil {
return nil, err
}
return c, nil
}
func getRemotePinService(env cmds.Environment, name string) (*pinclient.Client, error) {
if name == "" {
return nil, fmt.Errorf("remote pinning service name not specified")
}
endpoint, key, err := getRemotePinServiceInfo(env, name)
if err != nil {View on GitHub (pinned to 329838acdf)
Solutions
- Add the `--service=<name>` option: e.g. `ipfs pin remote ls --service=web3.storage`.
- Confirm the service is registered (`ipfs pin remote service ls` or config `Pinning.RemoteServices`) and use its exact name.
- Fix wrappers/automation to always pass `--service`; consult `ipfs pin remote <subcmd> --help` for the option name in your version.
Example fix
// before ipfs pin remote ls // after ipfs pin remote ls --service=web3.storage
Defensive patterns
Strategy: validation
Validate before calling
#!/usr/bin/env bash
: "${SERVICE:?--service is required}"
ipfs pin remote ls --service="${SERVICE}" Prevention
- Make --service a mandatory parameter in wrapper scripts
- List registered services first to pick a valid name
- Never rely on a default service name existing
When it happens
Trigger: Running `ipfs pin remote ls`, `add`, or `rm` operations without the `--service=<name>` option; or invoking the underlying command programmatically with `Options` missing the `pinServiceNameOptionName` key.
Common situations: Forgetting `--service` on `ipfs pin remote ls`; older tutorials/scripts that predate the required `--service` flag; wrapping the command in a tool that drops options.
Understand the failure class
Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.
Related errors
- expecting one argument: name
- no bootstrap peers to add
- cannot specify negative offset
- cannot specify negative length
- service already present
AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03).
Data as JSON: /api/errors/7f054fa08a8b0a9b.
Report an issue: GitHub.