{"record":{"id":"962006e50a6a3ad5","repo":"ipfs/kubo","slug":"paths-must-start-with-a-leading-slash","errorCode":null,"errorMessage":"paths must start with a leading slash","messagePattern":"paths must start with a leading slash","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/commands/files.go","lineNumber":1586,"sourceCode":"\n\t\tfi, ok := fsn.(*mfs.File)\n\t\tif !ok {\n\t\t\treturn nil, errors.New(\"expected *mfs.File, didn't get it. This is likely a race condition\")\n\t\t}\n\t\treturn fi, nil\n\n\tdefault:\n\t\treturn nil, err\n\t}\n}\n\nfunc checkPath(p string) (string, error) {\n\tif len(p) == 0 {\n\t\treturn \"\", fmt.Errorf(\"paths must not be empty\")\n\t}\n\n\tif p[0] != '/' {\n\t\treturn \"\", fmt.Errorf(\"paths must start with a leading slash\")\n\t}\n\n\tcleaned := gopath.Clean(p)\n\tif p[len(p)-1] == '/' && p != \"/\" {\n\t\tcleaned += \"/\"\n\t}\n\treturn cleaned, nil\n}\n\nfunc getParentDir(root *mfs.Root, dir string) (*mfs.Directory, error) {\n\tparent, err := mfs.Lookup(root, dir)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tpdir, ok := parent.(*mfs.Directory)\n\tif !ok {\n\t\treturn nil, errors.New(\"expected *mfs.Directory, didn't get it. This is likely a race condition\")","sourceCodeStart":1568,"sourceCodeEnd":1604,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/commands/files.go#L1568-L1604","documentation":"checkPath in core/commands/files.go requires MFS paths to be absolute, i.e. start with '/'. MFS is rooted at '/', and commands like `files chchunk`/`files chmod` (and the shared path-check helper) reject relative or malformed paths with this error after cleaning is considered.","triggerScenarios":"Calling a files command with a relative path such as `dir/file.txt` instead of `/dir/file.txt`; passing a Windows-style path `C:\\...`; a path built by string concatenation that lost its leading slash.","commonSituations":"Users treating MFS like the local filesystem (using relative paths from a working directory); scripts stripping the leading slash with cut/sed; API clients sending un-normalized paths.","solutions":["Prefix the argument with '/' if it does not already start with one.","Always pass absolute paths under the MFS root, e.g. `/dir/file.txt`.","Normalize/validate paths in scripts before calling the command (e.g. with `realpath -m` style logic, then prepend '/')."],"exampleFix":"// before\nipfs files ls dir/file.txt   # paths must start with a leading slash\n// after\nipfs files ls /dir/file.txt","handlingStrategy":"validation","validationCode":"case \"$P\" in /*) ;; *) P=\"/$P\" ;; esac","typeGuard":"func isAbsolute(p string) bool { return strings.HasPrefix(p, \"/\") }","tryCatchPattern":"cleaned, err := checkPath(p)\nif err != nil {\n    if strings.Contains(err.Error(), \"leading slash\") { return fmt.Errorf(\"MFS paths must be absolute, got %q\", p) }\n    return err\n}","preventionTips":["Always write MFS paths with a leading slash","Do not strip the leading slash when post-processing paths in scripts","Use one path-normalization helper across automation"],"tags":["validation","mfs","path","cli"],"backgroundTag":"relative-path-not-allowed","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"}