{"record":{"id":"8fbb3fad96cd865b","repo":"ipfs/kubo","slug":"this-dag-node-is-not-a-regular-file","errorCode":null,"errorMessage":"this dag node is not a regular file","messagePattern":"this dag node is not a regular file","errorType":"exception","errorClass":"ErrNotFile","httpStatus":null,"severity":"error","filePath":"core/coreiface/errors.go","lineNumber":7,"sourceCode":"package iface\n\nimport \"errors\"\n\nvar (\n\tErrIsDir        = errors.New(\"this dag node is a directory\")\n\tErrNotFile      = errors.New(\"this dag node is not a regular file\")\n\tErrOffline      = errors.New(\"this action must be run in online mode, try running 'ipfs daemon' first\")\n\tErrNotSupported = errors.New(\"operation not supported\")\n)\n","sourceCodeStart":1,"sourceCodeEnd":11,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/coreiface/errors.go#L1-L11","documentation":"`iface.ErrNotFile` is a sentinel error meaning the DAG node being accessed is not a regular UnixFS file. Unlike ErrIsDir (which specifically identifies directories), this covers other non-file node kinds — for example raw nodes, symlinks, or metadata nodes — for operations that require regular file content.","triggerScenarios":"Invoking file-content operations (Unixfs Get/Cat with file expectations, or APIs that coerce the node to a files.File) on a CID/path that resolves to a non-regular-file node type (symlink, raw leaf, hamt-shard metadata, etc.).","commonSituations":"`ipfs cat` on a symlink node created via `ipfs files` with unixfs symlinks; attempting to read a shard/hamt internal node directly by CID; tooling that inspects DAG internals and hands internal node CIDs to file APIs.","solutions":["Verify the target's node type first (e.g. `ipfs dag get` or `ipfs files stat`) and use the appropriate API for that node kind.","If the node is a symlink, resolve the link target and request that path instead.","In code, check `errors.Is(err, iface.ErrNotFile)` and branch to a generic DAG reader (`api.Dag().Get`) instead of the UnixFS file reader."],"exampleFix":"// before\nf, err := api.Unixfs().Get(ctx, p) // fails on symlink\n// after\nnode, err := api.Unixfs().Get(ctx, p)\nif errors.Is(err, iface.ErrNotFile) {\n    var ig pb.UnixFSData\n    return inspectWithDagAPI(ctx, api, p) // generic dag handling\n}","handlingStrategy":"type-guard","validationCode":"// Inspect the node before file operations:\nout, err := api.Dag().Get(ctx, c) // then check unixfs data type (symlink, raw, etc.)","typeGuard":"func isRegularFile(node files.Node) bool {\n    _, ok := node.(files.File)\n    return ok\n}","tryCatchPattern":"node, err := api.Unixfs().Get(ctx, p)\nif err != nil {\n    if errors.Is(err, iface.ErrNotFile) {\n        return readViaDagAPI(ctx, p) // symlink/raw node handling\n    }\n    return err\n}","preventionTips":["Check node type with `ipfs dag get` or `ipfs files stat` before reading content","Resolve unixfs symlinks to their target path before cat","Do not feed internal DAG node CIDs (shard/hamt internals) to file APIs"],"tags":["unixfs","coreapi","sentinel-error","ipfs"],"backgroundTag":"node-is-not-regular-file","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"}