{"record":{"id":"2b784a5100b0313a","repo":"gastownhall/beads","slug":"failed-to-scan-jsonl-w-2b784a","errorCode":null,"errorMessage":"failed to scan JSONL: %w","messagePattern":"failed to scan JSONL: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/import_shared.go","lineNumber":1056,"sourceCode":"\t\t// Regular issue record\n\t\tvar issue types.Issue\n\t\tif err := json.Unmarshal([]byte(line), &issue); err != nil {\n\t\t\treturn nil, nil, fmt.Errorf(\"failed to parse issue from JSONL: %w\", err)\n\t\t}\n\t\t// Skip tombstone entries: these are deleted issues exported by older\n\t\t// versions (pre-v0.50) with status \"tombstone\" and deleted_at set.\n\t\t// They are not valid for re-import since \"tombstone\" is not a real status.\n\t\tif issue.Status == \"tombstone\" {\n\t\t\tcontinue\n\t\t}\n\n\t\tapplyImportWispPlane(peek, &issue)\n\n\t\tissue.SetDefaults()\n\t\tissues = append(issues, &issue)\n\t}\n\tif err := scanner.Err(); err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"failed to scan JSONL: %w\", err)\n\t}\n\n\treturn issues, configEntries, nil\n}\n\n// applyImportWispPlane resolves which storage plane (wisps vs issues table) a\n// parsed import record routes to, shared by every JSONL parse loop\n// (parseImportRecords for `bd import` in both storage modes, parseJSONLFile\n// for bootstrap / init --from-jsonl / auto-import).\n//\n// The \"wisp_plane\" peek key is the EXPLICIT wisps-plane marker (bd-r9uce):\n// export writes it for rows that live in the wisps table, precisely because\n// row flags cannot be trusted for the plane decision — a promoted no-history\n// wisp is a durable issues-table row that may still carry no_history=true\n// (PromoteFromEphemeralInTx used to clear only Ephemeral, and wild data\n// with that shape persists). Routing such a record by flags re-planes it\n// into the wisps table, after which its cross-plane relations are dropped\n// by the batch import and the row itself is no longer durable — silent data","sourceCodeStart":1038,"sourceCodeEnd":1074,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/import_shared.go#L1038-L1074","documentation":"After parsing all lines of a JSONL file, parseJSONLFile checks bufio.Scanner.Err(). This error fires when the underlying reader itself failed (I/O error reading the file), as opposed to a per-line JSON problem — a distinct failure from the line-parse errors.","triggerScenarios":"During parseJSONLFile (auto-import, bootstrap, init --from-jsonl), the scanner reading the JSONL file hits an I/O error: the file was deleted/truncated mid-read, the filesystem returned EIO, a network mount dropped, or the path is a special file that errors on read.","commonSituations":".beads/issues.jsonl lives on an NFS/cloud-synced folder that disconnected mid-import; the file was replaced or truncated while `bd` ran; disk errors or permissions changing mid-read; reading a FIFO/device that errored.","solutions":["Re-run the command — transient I/O errors (network mount blips) often clear on retry","Verify the file exists and is readable: `ls -l .beads/issues.jsonl && head -1 .beads/issues.jsonl`","Check filesystem/mount health (dmesg for I/O errors; remount the network share)","Regenerate the JSONL with `bd export` if the file is damaged, then re-import"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"f, err := os.Open(path)\nif err != nil { return err }\nst, err := f.Stat()\nif err != nil { return err }\nif !st.Mode().IsRegular() { return fmt.Errorf(\"%s is not a regular file\", path) }\nf.Close()","typeGuard":null,"tryCatchPattern":"if _, _, err := parseJSONLFile(path); err != nil {\n    if strings.Contains(err.Error(), \"failed to scan JSONL\") {\n        // transient I/O: back off and retry\n        time.Sleep(2 * time.Second)\n        return parseJSONLFile(path)\n    }\n    return err\n}","preventionTips":["Keep .beads/ off flaky network mounts or wait for sync tools (Dropbox/Drive) to settle","Avoid reading the JSONL while another process is rewriting it","Monitor disk health if I/O errors recur","Use local filesystem storage for Dolt data"],"tags":["jsonl","io-error","scanner","import"],"backgroundTag":"file-read-io-error","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}