{"record":{"id":"fd70479b65e96c14","repo":"ipfs/kubo","slug":"api-flag-specified-but-command-cannot-be-run-on-th","errorCode":null,"errorMessage":"api flag specified but command cannot be run on the daemon","messagePattern":"api flag specified but command cannot be run on the daemon","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/ipfs/kubo/start.go","lineNumber":285,"sourceCode":"\t\t}\n\t}\n\n\t// Get the API option from the commandline.\n\tapiAddr, err := apiAddrOption(req)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\t// Require that the command be run on the daemon when the API flag is\n\t// passed (unless we're trying to _run_ the daemon).\n\tdaemonRequested := apiAddr != nil && req.Command != daemonCmd\n\n\t// Run this on the client if required.\n\tif req.Command.NoRemote {\n\t\tif daemonRequested {\n\t\t\t// User requested that the command be run on the daemon but we can't.\n\t\t\t// NOTE: We drop this check for the `ipfs daemon` command.\n\t\t\treturn nil, errors.New(\"api flag specified but command cannot be run on the daemon\")\n\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 {","sourceCodeStart":267,"sourceCodeEnd":303,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/cmd/ipfs/kubo/start.go#L267-L303","documentation":"When a command is marked NoRemote it must execute in the CLI client process, but the user also passed --api (or the request implies the daemon), which forces daemon execution. makeExecutor detects this contradiction and fails with 'api flag specified but command cannot be run on the daemon'. The ipfs daemon command itself is exempted from this check.","triggerScenarios":"Running a NoRemote command (commands that must touch local files/repo directly, e.g. some `ipfs daemon`-adjacent or repo commands) while passing `--api /ip4/.../tcp/5001` on the command line; also IPFS_PATH-based API discovery is bypassed, so only an explicit --api triggers this branch.","commonSituations":"Shell aliases or scripts that always append `--api $ADDR` to every ipfs call, then hitting a command that forbids remote execution; CI wrappers that set the api flag globally; misunderstanding that --api is merely a hint — for NoRemote commands it is a hard error.","solutions":["Remove the `--api` flag for this command so it runs locally in the client process.","If you intended daemon execution, verify the command actually supports remote mode; if not, run it on the machine hosting the repo without --api.","Fix wrapper scripts to only add --api for remote-capable commands instead of unconditionally."],"exampleFix":"# before\nipfs --api /ip4/127.0.0.1/tcp/5001 <no-remote-command>\n# after\nipfs <no-remote-command>","handlingStrategy":"validation","validationCode":"// in a wrapper script: only add --api for remote-capable commands\nif ! case \" $NO_REMOTE_CMDS \" in *\" $cmd \"*) true;; *) false;; esac; then\n  args=(--api \"$IPFS_API\" \"${args[@]}\")\nfi","typeGuard":"func apiFlagAllowed(cmd *cmds.Command) bool {\n    return !cmd.NoRemote\n}","tryCatchPattern":"err := runIPFS(args...)\nif err != nil && strings.Contains(err.Error(), \"api flag specified but command cannot be run on the daemon\") {\n    // retry without the --api flag\n    args = removeFlag(args, \"--api\")\n    err = runIPFS(args...)\n}","preventionTips":["Never set --api globally (e.g. via alias or IPFS wrapper); apply it per command.","Know which commands are client-only (NoRemote) before scripting them.","Test wrapper scripts against every command they emit."],"tags":["cli","kubo","api-flag","conflicting-options"],"backgroundTag":"api-flag-not-supported","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"}