{"record":{"id":"bc3b75e3b3f625c9","repo":"affaan-m/ECC","slug":"pandoc-did-not-produce-a-nonempty-regular-docx-artifact","errorCode":null,"errorMessage":"pandoc did not produce a nonempty regular DOCX artifact","messagePattern":"pandoc did not produce a nonempty regular DOCX artifact","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"skills/master-agreement-generator/scripts/build-agreement.js","lineNumber":188,"sourceCode":"  // beside a newly built Markdown draft, including explicit Markdown-only builds.\n  fs.rmSync(docxPath, { force: true });\n  const result = { markdown: mdPath, docx: null, docxSkipped: false, documentStatus: 'draft' };\n  if (options.markdownOnly === true) {\n    result.docxSkipped = true;\n    return result;\n  }\n  const canConvert = options.pandoc === undefined ? pandocAvailable() : options.pandoc;\n  if (!canConvert) {\n    throw new Error('DOCX required: pandoc unavailable; use --markdown-only for an explicit Markdown-only draft');\n  }\n  try {\n    const converted = spawnSync('pandoc', [mdPath, '-o', docxPath], CONVERTER_OPTIONS);\n    if (converted.error || converted.status !== 0) {\n      throw new Error('pandoc conversion failed; DOCX unavailable');\n    }\n    const artifact = fs.lstatSync(docxPath);\n    if (!artifact.isFile() || artifact.size === 0) {\n      throw new Error('pandoc did not produce a nonempty regular DOCX artifact');\n    }\n  } catch (error) {\n    fs.rmSync(docxPath, { force: true });\n    if (error.code === 'ENOENT') throw new Error('pandoc did not produce a DOCX artifact');\n    throw error;\n  }\n  result.docx = docxPath;\n  return result;\n}\n\nfunction main(argv) {\n  const [templatePath, specPath, outDir, ...flags] = argv;\n  if (!templatePath || !specPath || !outDir ||\n      flags.some(flag => !['--require-docx', '--markdown-only'].includes(flag)) ||\n      flags.length > 1) {\n    console.error('usage: build-agreement.js <template.md> <spec.json> <out_dir> [--require-docx | --markdown-only]');\n    return 2;\n  }","sourceCodeStart":170,"sourceCodeEnd":206,"githubUrl":"https://github.com/affaan-m/ECC/blob/8321021c54d670126ce3b2969d5deb880b4b0c2a/skills/master-agreement-generator/scripts/build-agreement.js#L170-L206","documentation":"After a nominally successful pandoc run, build() verifies the artifact: it lstat's the DOCX path and requires a regular, non-empty file. If pandoc reported success but produced nothing usable (zero-byte file, directory, missing file), this error is thrown, the stale/partial docx is removed, and ENOENT is remapped to the clearer 'pandoc did not produce a DOCX artifact' message.","triggerScenarios":"Pandoc exits 0 but writes to a different location, a zero-length .docx from a silently failing filter, or something (another process/cleanup hook) deleting the file between conversion and the lstat check.","commonSituations":"Flaky/silently failing pandoc filters or Lua filters; disk-full conditions yielding truncated/empty output; racing background jobs cleaning the output directory mid-build.","solutions":["Check the output directory after failure — confirm whether any DOCX exists and its size (ls -la out/).","Run pandoc manually with the same command and inspect its output/exit code for silent filter failures.","Free up disk space if the volume is full; a full disk commonly yields empty artifacts.","Rerun in an isolated output directory to rule out concurrent processes deleting the artifact."],"exampleFix":"// before\n$ pandoc md -o docx && echo ok   # exit 0, but docx is 0 bytes\n// after\n$ df -h .            # rule out disk-full\n$ pandoc md -o docx --verbose   # surface silent filter failures\n$ node build-agreement.js --spec spec.json --out out  # retry","handlingStrategy":"retry","validationCode":"const fs = require('fs');\nfunction verifyDocxArtifact(p) {\n  const st = fs.lstatSync(p); // throws ENOENT if missing\n  if (!st.isFile() || st.size === 0) throw new Error('DOCX artifact missing or empty');\n}\nverifyDocxArtifact(`${outDir}/${spec.file} MASTER.docx`);","typeGuard":"null","tryCatchPattern":"try {\n  build(templatePath, specPath, outDir);\n} catch (e) {\n  if (e.message.includes('DOCX artifact')) {\n    console.error('pandoc exited 0 but produced no usable DOCX; check filters and disk space');\n  } else throw e;\n}","preventionTips":["Ensure adequate disk space before conversion; full disks commonly produce empty artifacts.","Avoid pandoc filters that can fail silently while still exiting 0.","Run builds in a dedicated output directory so concurrent cleanup jobs can't delete artifacts mid-run."],"tags":["pandoc","artifact","filesystem"],"backgroundTag":"external-command-failed","analyzedSha":"8321021c54d670126ce3b2969d5deb880b4b0c2a","analyzedAt":"2026-09-16T10:08:13.343Z","contentChangedAt":"2026-09-16T10:08:13.343Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}