{"record":{"id":"b146f9d1705a704b","repo":"ipfs/kubo","slug":"pinning-service-not-available","errorCode":null,"errorMessage":"pinning service not available","messagePattern":"pinning service not available","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/commands/pin/pin.go","lineNumber":471,"sourceCode":"\t\tcmds.StringOption(pinTypeOptionName, \"t\", \"The type of pinned keys to list. Can be \\\"direct\\\", \\\"indirect\\\", \\\"recursive\\\", or \\\"all\\\".\").WithDefault(\"all\"),\n\t\tcmds.BoolOption(pinQuietOptionName, \"q\", \"Output only the CIDs of pins.\"),\n\t\tcmds.StringOption(pinNameOptionName, \"n\", \"Limit returned pins to ones with names that contain the value provided (case-sensitive, partial match). Implies --names=true.\"),\n\t\tcmds.BoolOption(pinStreamOptionName, \"s\", \"Enable streaming of pins as they are discovered.\"),\n\t\tcmds.BoolOption(pinNamesOptionName, \"Include pin names in the output (slower, disabled by default).\"),\n\t},\n\tRun: func(req *cmds.Request, res cmds.ResponseEmitter, env cmds.Environment) error {\n\t\tapi, err := cmdenv.GetApi(env, req)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\tn, err := cmdenv.GetNode(env)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\tif n.Pinning == nil {\n\t\t\treturn fmt.Errorf(\"pinning service not available\")\n\t\t}\n\n\t\ttypeStr, _ := req.Options[pinTypeOptionName].(string)\n\t\tstream, _ := req.Options[pinStreamOptionName].(bool)\n\t\tdisplayNames, _ := req.Options[pinNamesOptionName].(bool)\n\t\tname, _ := req.Options[pinNameOptionName].(string)\n\n\t\t// Validate name filter\n\t\tif err := cmdutils.ValidatePinName(name); err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\tmode, ok := pin.StringToMode(typeStr)\n\t\tif !ok {\n\t\t\treturn fmt.Errorf(\"invalid type '%s', must be one of {direct, indirect, recursive, all}\", typeStr)\n\t\t}\n\n\t\t// For backward compatibility, we accumulate the pins in the same output type as before.","sourceCodeStart":453,"sourceCodeEnd":489,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/commands/pin/pin.go#L453-L489","documentation":"The `ipfs pin` commands (rm/ls) require a pinning subsystem on the node. When the node runs with a remote pinning service only (no local pinning, e.g. `Pinning` is nil because the node was constructed without local pinning support), kubo returns this error. Local pin operations are impossible without it.","triggerScenarios":"Running `ipfs pin rm <cid>` (or ls) against a node whose CoreAPI `Pinning` is nil — a node configured without a local pinning implementation (e.g. certain cluster/remote-only setups).","commonSituations":"Running pin commands against a node that delegates pinning to ipfs-cluster or a remote pinning service; stripped-down library-embedded nodes (kubo-as-a-library) built without pinning.","solutions":["Run the command against a full kubo daemon with local pinning enabled.","Use the remote pinning API instead: `ipfs pin remote add/rm/ls --service=<name>` for service-based pinning.","If embedding kubo, ensure the node constructor wires a pinning implementation into the CoreAPI.","Check `ipfs config Pinning` to confirm which pinning services are configured locally."],"exampleFix":"// before\nclient.Request(\"pin/rm\", cid).Send(ctx)\n// after — remote pinning path for service-only nodes\nclient.Request(\"pin/remote/rm\").Option(\"service\", \"pinata\").Arguments(cid).Send(ctx)","handlingStrategy":"fallback","validationCode":"idOut, err := client.Request(\"id\").Send(ctx) // full daemons support local pinning\n// for service-only nodes, prefer pin/remote endpoints","typeGuard":null,"tryCatchPattern":"if _, err := client.Request(\"pin/rm\", cid).Send(ctx); err != nil {\n    if strings.Contains(err.Error(), \"pinning service not available\") {\n        return client.Request(\"pin/remote/rm\").Option(\"service\", svc).Arguments(cid).Send(ctx)\n    }\n    return err\n}","preventionTips":["Use pin/remote/* APIs against cluster or remote-pinning setups","Ensure embedded nodes wire a pinning implementation","Check node capabilities before issuing local pin commands"],"tags":["ipfs","cli","pinning","configuration"],"backgroundTag":"pinning-service-unavailable","analyzedSha":"329838acdfafae224582930457efe80aa217afc0","analyzedAt":"2026-09-03T18:30:52.135Z","contentChangedAt":"2026-09-03T18:30:52.135Z","schemaVersion":2},"datasetVersion":"2026-09-11T00:17:11.886Z"}