{"record":{"id":"be2410258029d595","repo":"ipfs/kubo","slug":"command-must-be-run-on-the-daemon-v","errorCode":null,"errorMessage":"command must be run on the daemon: %v","messagePattern":"command must be run on the daemon: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/ipfs/kubo/start.go","lineNumber":304,"sourceCode":"\t\t}\n\t\treturn exe, nil\n\t}\n\n\t// Finally, look in the repo for an API file.\n\tif apiAddr == nil {\n\t\tvar err error\n\t\tapiAddr, err = fsrepo.APIAddr(cctx.ConfigRoot)\n\t\tswitch err {\n\t\tcase nil, repo.ErrApiNotRunning:\n\t\tdefault:\n\t\t\treturn nil, err\n\t\t}\n\t}\n\n\t// Still no api specified? Run it on the client or fail.\n\tif apiAddr == nil {\n\t\tif req.Command.NoLocal {\n\t\t\treturn nil, fmt.Errorf(\"command must be run on the daemon: %v\", req.Path)\n\t\t}\n\t\treturn exe, nil\n\t}\n\n\t// Resolve the API addr.\n\t//\n\t// Do not replace apiAddr with the resolved addr so that the requested\n\t// hostname is kept for use in the request's HTTP header.\n\t_, err = resolveAddr(req.Context, apiAddr)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tnetwork, host, err := manet.DialArgs(apiAddr)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\t// Construct the executor.","sourceCodeStart":286,"sourceCodeEnd":322,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/cmd/ipfs/kubo/start.go#L286-L322","documentation":"The command requires daemon execution (NoLocal set) but no API address could be found: neither --api was given nor an API file present in the repo (fsrepo.APIAddr returned nil/ErrApiNotRunning). makeExecutor then fails with 'command must be run on the daemon: <path>' because the command cannot run in the client.","triggerScenarios":"Running a NoLocal command (e.g. most repo-mutating commands like `ipfs add`, `ipfs pin`) when no daemon is running and no --api flag is supplied; the repo exists but its API file is missing, stale, or the daemon was not started.","commonSituations":"Forgetting `ipfs daemon` before running commands on a server; daemon crashed leaving a stale API file (usually yields ErrApiNotRunning path instead); running commands with a different IPFS_PATH than the running daemon's, so the API file isn't found.","solutions":["Start the daemon first: `ipfs daemon` (or `systemctl start ipfs`), then re-run the command.","Pass the daemon's address explicitly: `ipfs --api /ip4/127.0.0.1/tcp/5001 <cmd>`.","Ensure IPFS_PATH points to the same repo the daemon uses (default ~/.ipfs); check the api file exists at $IPFS_PATH/api and matches the running daemon."],"exampleFix":"# before\nipfs add myfile.txt            # daemon not running\n# after\nipfs daemon &\nipfs --api /ip4/127.0.0.1/tcp/5001 add myfile.txt","handlingStrategy":"fallback","validationCode":"if ! ipfs swarm peers >/dev/null 2>&1; then\n  echo \"daemon not running; starting it\" >&2\n  nohup ipfs daemon >/dev/null 2>&1 &\n  until ipfs swarm peers >/dev/null 2>&1; do sleep 0.5; done\nfi","typeGuard":"func daemonReachable() bool {\n    _, err := os.Stat(filepath.Join(os.Getenv(\"IPFS_PATH\"), \"api\"))\n    return err == nil\n}","tryCatchPattern":"out, err := run(\"ipfs\", args...)\nif err != nil && strings.Contains(out+err.Error(), \"must be run on the daemon\") {\n    startDaemon() // then retry once\n    out, err = run(\"ipfs\", args...)\n}","preventionTips":["Always ensure the daemon is running before repo-mutating commands in scripts.","Keep IPFS_PATH consistent between daemon and client invocations.","Use systemd/supervisor to keep the daemon up rather than ad-hoc starts.","Health-check `ipfs id --api <addr>` before batch operations."],"tags":["cli","kubo","daemon-not-running"],"backgroundTag":"daemon-not-running","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"}