ipfs/kubo · error

files rm always flushes for safety. The --flush flag cannot

Error message

files rm always flushes for safety. The --flush flag cannot be set to false for this command

What it means

Precondition check in the `ipfs files rm` handler: the command inspects whether the caller explicitly passed --flush=false and rejects it. `files rm` always flushes the affected parent directories so removals are persisted immediately; disabling flush for a destructive operation is disallowed by design, not an operational failure.

Source

Thrown at core/commands/files.go:1393

    cat
    dog
    fish
    $ ipfs files rm -r /bar
`,
	},

	Arguments: []cmds.Argument{
		cmds.StringArg("path", true, true, "File to remove."),
	},
	Options: []cmds.Option{
		cmds.BoolOption(recursiveOptionName, "r", "Recursively remove directories."),
		cmds.BoolOption(forceOptionName, "Forcibly remove target at path; implies -r for directories"),
	},
	Run: func(req *cmds.Request, res cmds.ResponseEmitter, env cmds.Environment) error {
		// Check if user explicitly set --flush=false
		if flushOpt, ok := req.Options[filesFlushOptionName]; ok {
			if flush, ok := flushOpt.(bool); ok && !flush {
				return fmt.Errorf("files rm always flushes for safety. The --flush flag cannot be set to false for this command")
			}
		}

		nd, err := cmdenv.GetNode(env)
		if err != nil {
			return err
		}
		defer mfsPinLock(nd, req.Context).Unlock(req.Context)
		// if '--force' specified, it will remove anything else,
		// including file, directory, corrupted node, etc
		force, _ := req.Options[forceOptionName].(bool)
		dashr, _ := req.Options[recursiveOptionName].(bool)
		var errs []error
		for _, arg := range req.Arguments {
			path, err := checkPath(arg)
			if err != nil {
				errs = append(errs, fmt.Errorf("%s is not a valid path: %w", arg, err))
				continue

View on GitHub (pinned to 329838acdf)

Solutions

1. Do not pass --flush=false with `ipfs files rm`; accept the default flush behavior.
2. For non-flushing write workflows use `ipfs files write`/`mkdir` with --flush=false instead.

When it happens

Trigger: Thrown at core/commands/files.go:1393 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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