ipfs/kubo · error

%s can't be used with UnixFS metadata like mode or modificat

Error message

%s can't be used with UnixFS metadata like mode or modification time

What it means

UnixFS 1.5 metadata (mode or mtime) must live in a dag-pb root node; --raw-leaves produces raw blocks that cannot carry this metadata. Kubo refuses the command when raw-leaves was explicitly requested together with mode/mtime metadata, so the user makes the choice consciously.

Source

Thrown at core/commands/add.go:434

		fastProvideRoot = config.ResolveBoolFromConfig(fastProvideRoot, fastProvideRootSet, cfg.Import.FastProvideRoot, config.DefaultFastProvideRoot)
		fastProvideDAG = config.ResolveBoolFromConfig(fastProvideDAG, fastProvideDAGSet, cfg.Import.FastProvideDAG, config.DefaultFastProvideDAG)
		fastProvideWait = config.ResolveBoolFromConfig(fastProvideWait, fastProvideWaitSet, cfg.Import.FastProvideWait, config.DefaultFastProvideWait)

		// --only-hash does not store data, so pinning and providing
		// are meaningless.
		if onlyHash {
			dopin = false
			fastProvideRoot = false
			fastProvideDAG = false
		}

		// Storing optional mode or mtime (UnixFS 1.5) requires root block
		// to always be 'dag-pb' and not 'raw'. Below adjusts raw-leaves setting, if possible.
		if preserveMode || preserveMtime || mode != 0 || mtime != 0 {
			// Error if --raw-leaves flag was explicitly passed by the user.
			// (let user make a decision to manually disable it and retry)
			if rbset && rawblks {
				return fmt.Errorf("%s can't be used with UnixFS metadata like mode or modification time", rawLeavesOptionName)
			}
			// No explicit preference from user, disable raw-leaves and continue
			rbset = true
			rawblks = false
		}

		if onlyHash && toFilesSet {
			return fmt.Errorf("%s and %s options are not compatible", onlyHashOptionName, toFilesOptionName)
		}
		if !dopin && pinNameSet {
			return fmt.Errorf("%s option requires %s to be set", pinNameOptionName, pinOptionName)
		}
		if wrap && toFilesSet {
			return fmt.Errorf("%s and %s options are not compatible", wrapOptionName, toFilesOptionName)
		}

		hashFunCode, ok := mh.Names[strings.ToLower(hashFunStr)]
		if !ok {

View on GitHub (pinned to 329838acdf)

Solutions

1. Remove --raw-leaves so kubo auto-disables it when metadata is present
2. Explicitly pass --raw-leaves=false to override config
3. Drop the mode/mtime/preserve flags if raw-leaves output matters more

Example fix

// before
ipfs add --raw-leaves --preserve-mtime ./photos
// after
ipfs add --preserve-mtime ./photos

if rawLeaves && (mode != 0 || mtime != 0 || preserveMode || preserveMtime) {
  return errors.New("--raw-leaves cannot be combined with mode/mtime metadata")
}

When it happens

Trigger: `ipfs add --raw-leaves --preserve-mtime <path>`; `ipfs add --raw-leaves --mode=644 file`; any add where --raw-leaves was explicitly passed (or forced via config Import.UnixFSRawLeaves=true) alongside --mode, --mtime, --preserve-mode or --preserve-mtime.

Common situations: Archiving scripts preserving timestamps while enabling raw-leaves for deterministic CIDs; global config setting Import.UnixFSRawLeaves=true, then adding files with metadata flags.

Related errors

• option %q requires %q to be provided as well
• invalid configuration profile: %s
• Import.UnixFSFileMaxLinks must be positive, got %d
• Import.UnixFSDirectoryMaxLinks must be non-negative, got %d
• Import.UnixFSHAMTDirectoryMaxFanout must be a power of 2, be

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