{"record":{"id":"cb99c23b83aa2267","repo":"affaan-m/ECC","slug":"pandoc-conversion-failed-docx-unavailable","errorCode":null,"errorMessage":"pandoc conversion failed; DOCX unavailable","messagePattern":"pandoc conversion failed; DOCX unavailable","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"skills/master-agreement-generator/scripts/build-agreement.js","lineNumber":184,"sourceCode":"  fs.mkdirSync(root, { recursive: true });\n  fs.writeFileSync(mdPath, markdown, 'utf8');\n\n  // Generated DOCX is replaceable output. Never leave a stale or partial copy\n  // 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)) ||","sourceCodeStart":166,"sourceCodeEnd":202,"githubUrl":"https://github.com/affaan-m/ECC/blob/8321021c54d670126ce3b2969d5deb880b4b0c2a/skills/master-agreement-generator/scripts/build-agreement.js#L166-L202","documentation":"When pandoc is present, build() spawns `pandoc <mdPath> -o <docxPath>` and throws this error if the spawn itself errored (converted.error) or pandoc exited non-zero. Unlike error 727 (pandoc not found at all), this means conversion was attempted and failed, so the DOCX output is unavailable and any partial docx is cleaned up.","triggerScenarios":"Pandoc installed but failing on the generated Markdown (unsupported construct, huge tables); a broken pandoc install or incompatible version; converted.error from spawn failure (e.g. EACCES on the pandoc binary).","commonSituations":"Very old pandoc versions choking on newer Markdown features; restricted CI environments where the pandoc binary can't execute; intermediary pandoc filters failing and returning a non-zero exit code.","solutions":["Run `pandoc <mdPath> -o <docxPath>` manually on the generated .md to see pandoc's actual stderr.","Upgrade or reinstall pandoc to a current version (pandoc --version).","Simplify/inspect the generated Markdown near any nonstandard content (wide tables, raw HTML) that pandoc may reject.","If the spawn error was EACCES/ENOENT rather than a pandoc failure, fix the binary's permissions or PATH."],"exampleFix":"// before\n$ pandoc out/NDA\\ MASTER.md -o out/NDA\\ MASTER.docx\npandoc: unrecognized option `--xyz' (exit 1)\n// after\n$ pandoc --version   # check/upgrade version\n$ brew upgrade pandoc  # or apt-get install --only-upgrade pandoc\n$ node build-agreement.js --spec spec.json --out out  # retry","handlingStrategy":"retry","validationCode":"const { spawnSync } = require('child_process');\nconst probe = spawnSync('pandoc', ['--version']);\nif (probe.error || probe.status !== 0) throw new Error('pandoc broken or not executable');","typeGuard":"null","tryCatchPattern":"try {\n  build(templatePath, specPath, outDir);\n} catch (e) {\n  if (e.message === 'pandoc conversion failed; DOCX unavailable') {\n    console.error('Run pandoc manually on the .md to see the real error; check pandoc version');\n  } else throw e;\n}","preventionTips":["Pin a known-good pandoc version in dev/CI to avoid version-specific Markdown failures.","Keep generated Markdown within pandoc-friendly constructs (simple tables, no exotic raw HTML).","On failure, reproduce with the raw pandoc command to capture stderr the library swallows into a generic message."],"tags":["pandoc","conversion","process"],"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"}