{"record":{"id":"e663584ac328d757","repo":"ipfs/kubo","slug":"cp-cannot-unlink-existing-file-s","errorCode":null,"errorMessage":"cp: cannot unlink existing file: %s","messagePattern":"cp: cannot unlink existing file: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/commands/files.go","lineNumber":585,"sourceCode":"\n\t\tmkParents, _ := req.Options[filesParentsOptionName].(bool)\n\t\tif mkParents {\n\t\t\tmaxDirLinks := int(cfg.Import.UnixFSDirectoryMaxLinks.WithDefault(config.DefaultUnixFSDirectoryMaxLinks))\n\t\t\tsizeEstimationMode := cfg.Import.HAMTSizeEstimationMode()\n\t\t\terr := ensureContainingDirectoryExists(nd.FilesRoot, dst,\n\t\t\t\tmfs.WithCidBuilder(prefix),\n\t\t\t\tmfs.WithMaxLinks(maxDirLinks),\n\t\t\t\tmfs.WithSizeEstimationMode(sizeEstimationMode),\n\t\t\t)\n\t\t\tif err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t}\n\n\t\tforce, _ := req.Options[forceOptionName].(bool)\n\t\tif force {\n\t\t\tif err = unlinkNodeIfExists(nd, dst); err != nil {\n\t\t\t\treturn fmt.Errorf(\"cp: cannot unlink existing file: %s\", err)\n\t\t\t}\n\t\t}\n\n\t\tflush, _ := req.Options[filesFlushOptionName].(bool)\n\n\t\tif err := updateNoFlushCounter(nd, flush); err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\terr = mfs.PutNode(nd.FilesRoot, dst, node)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"cp: cannot put node in path %s: %s\", dst, err)\n\t\t}\n\t\tif flush {\n\t\t\tif _, err := mfs.FlushPath(req.Context, nd.FilesRoot, dst); err != nil {\n\t\t\t\treturn fmt.Errorf(\"cp: cannot flush the created file %s: %s\", dst, err)\n\t\t\t}\n\t\t\t// Flush parent to clear directory cache and free memory.","sourceCodeStart":567,"sourceCodeEnd":603,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/commands/files.go#L567-L603","documentation":"`ipfs files cp --force` first unlinks an existing destination entry via unlinkNodeIfExists before placing the new node; this error wraps a failure during that unlink step. It means MFS could not remove the existing entry at dst (see errors 278/279 raised by the helper for the specific causes).","triggerScenarios":"Running `ipfs files cp --force <src> <dst>` where dst exists and unlinkNodeIfExists fails — e.g. the dst parent path component is not a directory, the existing child is itself a directory (not a TFile), or the MFS root is in a broken state.","commonSituations":"Using --force to overwrite a dst that is a directory; dst path contains a file as an intermediate component (`/a.txt/b`); MFS concurrently modified so parent lookup fails.","solutions":["Check what exists at dst with `ipfs files stat <dst>`; --force only unlinks existing files, not directories","Remove directories manually first: `ipfs files rm -r <dst>` then run cp without --force","Verify every component of the dst path except the last is a directory: `ipfs files ls <parent>`","Create missing parent directories with `ipfs files mkdir -p <parent>`"],"exampleFix":"// before: dst is a directory, cp --force cannot unlink it\nipfs files cp --force /ipfs/Qm... /my-dir\n// error: cp: cannot unlink existing file: not a file: /my-dir\n\n// after\nipfs files rm -r /my-dir\nipfs files cp /ipfs/Qm... /my-dir","handlingStrategy":"validation","validationCode":"// ensure parent dirs exist and dst is not a directory before cp --force\nrun(\"ipfs\", \"files\", \"mkdir\", \"-p\", filepath.Dir(dst))\nif statType(dst) == \"directory\" {\n    run(\"ipfs\", \"files\", \"rm\", \"-r\", dst)\n}","typeGuard":"func isExistingDirectory(dst string) bool {\n    out, err := run(\"ipfs\", \"files\", \"stat\", dst)\n    return err == nil && strings.Contains(out, \"directory\")\n}","tryCatchPattern":"if err := ipfsFilesCpForce(src, dst); err != nil {\n    if strings.Contains(err.Error(), \"cannot unlink existing file\") {\n        // inspect dst type; rm -r if directory, then retry\n    }\n}","preventionTips":["`ipfs files stat <dst>` before using --force","Remember --force unlinks files only, never directories","Validate intermediate path components are directories"],"tags":["mfs","cli","cp"],"backgroundTag":"mfs-unlink-failed","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"}