{"record":{"id":"f34816b5f5bde5f8","repo":"garrytan/gstack","slug":"image-is-not-a-regular-file-src","errorCode":null,"errorMessage":"image is not a regular file: ${src}","messagePattern":"image is not a regular file: (.+?)","errorType":"validation","errorClass":"StrictModeError","httpStatus":null,"severity":"warning","filePath":"make-pdf/src/diagram-prepass.ts","lineNumber":667,"sourceCode":"    if (!realFilePath.startsWith(inputRoot)) {\n      const msg = `image resolves OUTSIDE the input directory: ${src} → ${realFilePath}`;\n      if (opts.strict) throw new StrictModeError(msg + \" — move it under the markdown's directory or drop --strict\");\n      opts.warn(msg);\n    }\n\n    // Bound the read BEFORE reading: a markdown image pointing at a special\n    // file (fifo, device) would hang readFileSync, and a multi-GB file would\n    // exhaust memory before any policy ran.\n    let stat: fs.Stats;\n    try {\n      stat = fs.statSync(filePath);\n    } catch {\n      opts.warn(`image unreadable: ${src}`);\n      return buildMissingImagePlaceholder(src);\n    }\n    if (!stat.isFile()) {\n      const msg = `image is not a regular file: ${src}`;\n      if (opts.strict) throw new StrictModeError(msg);\n      opts.warn(msg);\n      return buildMissingImagePlaceholder(src);\n    }\n    if (stat.size > MAX_IMAGE_BYTES) {\n      const msg = `image exceeds ${Math.round(MAX_IMAGE_BYTES / 1024 / 1024)}MB cap: ${src} (${Math.round(stat.size / 1024 / 1024)}MB)`;\n      if (opts.strict) throw new StrictModeError(msg);\n      opts.warn(msg);\n      return buildMissingImagePlaceholder(src);\n    }\n\n    let buf = fs.readFileSync(filePath);\n    let dims = imageDims(buf);\n    let mime = dims?.mime ?? mimeFromExtension(filePath);\n\n    // Print-resolution normalization (D4): rasters only — SVG scales free.\n    if (dims && mime !== \"image/svg+xml\" && dims.width > maxPx) {\n      const tab = opts.getTab();\n      if (tab) {","sourceCodeStart":649,"sourceCodeEnd":685,"githubUrl":"https://github.com/garrytan/gstack/blob/94993f74012782fd94416dd44b8314f6363a13a4/make-pdf/src/diagram-prepass.ts#L649-L685","documentation":"StrictModeError thrown when a local image filePath exists and stat succeeds but stat.isFile() is false — i.e. the path is a directory, fifo, character/block device, or socket. Reading such a path could hang readFileSync (fifo) or produce garbage, so the pre-pass guards it; strict makes it fatal, otherwise warn + placeholder.","triggerScenarios":"inlineLocalImages() under --strict where the resolved image path is a directory (e.g. ![x](./assets) where assets is a folder), a named pipe, or a device file. The existence check passes (it exists) but stat.isFile() returns false.","commonSituations":"Markdown accidentally points at a directory (missing filename); a prank/malicious doc referencing /dev/zero or a fifo; a broken build that left a directory where a PNG should be; a path whose extension is .png but is actually a folder.","solutions":["Point the markdown src at an actual image file, not a directory or special file.","Remove any fifo/device node masquerading as an image in the assets folder.","Drop --strict to degrade to a warn + placeholder if appropriate.","Audit the assets directory for non-regular files (`find . -type p -o -type b -o -type c`)."],"exampleFix":"<!-- before: assets is a directory -->\n![x](./assets)\n\n<!-- after -->\n![x](./assets/logo.png)","handlingStrategy":"validation","validationCode":"import fs from 'node:fs';\nimport path from 'node:path';\n\nfunction findNonRegularImages(markdown: string, inputDir: string): string[] {\n  const re = /!\\[[^\\]]*\\]\\((?!https?:|data:)([^)]+)\\)/g;\n  const bad: string[] = [];\n  let m: RegExpExecArray | null;\n  while ((m = re.exec(markdown))) {\n    const p = path.resolve(inputDir, decodeURIComponent(m[1]));\n    try { if (!fs.statSync(p).isFile()) bad.push(m[1]); } catch { /* missing handled elsewhere */ }\n  }\n  return bad;\n}","typeGuard":"import { StrictModeError } from './diagram-prepass';\nfunction isStrictModeError(e: unknown): e is StrictModeError {\n  return e instanceof StrictModeError;\n}","tryCatchPattern":null,"preventionTips":["Reference image files, not directories.","Audit assets for special files (`find . \\\\( -type p -o -type b -o -type c -o -type s \\\\) -ls`).","Drop --strict only if you are certain non-regular files are acceptable.","Validate image extensions against actual file type before committing."],"tags":["make-pdf","image","filesystem","strict-mode","security"],"backgroundTag":null,"analyzedSha":"94993f74012782fd94416dd44b8314f6363a13a4","analyzedAt":"2026-08-12T04:06:23.140Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}