{"record":{"id":"7fbe6f3ab6bd153a","repo":"siyuan-note/siyuan","slug":"please-configure-settings-export-pandoc-pat","errorCode":null,"errorMessage":"Please configure [Settings - Export - Pandoc - Path to Pandoc executable] first","messagePattern":"Please configure \\[Settings - Export - Pandoc - Path to Pandoc executable\\] first","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kernel/model/export.go","lineNumber":1029,"sourceCode":"\t\tif footnotesDefBlock := tree.Root.ChildByType(ast.NodeFootnotesDefBlock); nil != footnotesDefBlock {\n\t\t\tfootnotesDefBlock.Unlink()\n\t\t}\n\t\treturn nil\n\t}); exportErr != nil {\n\t\tlogging.LogErrorf(\"export preview [%s] failed: %s\", id, exportErr)\n\t\treturn\n\t}\n\treturn\n}\n\nfunc ExportDocx(id, savePath string, removeAssets, merge bool) (fullPath string, err error) {\n\terr = withExportReadLockByBlockID(id, func() error {\n\t\tpandocRuntime := util.GetPandocRuntime()\n\t\tif !util.IsValidPandocBin(pandocRuntime.BinPath) {\n\t\t\tutil.InitPandoc(Conf.Export.PandocBin)\n\t\t\tpandocRuntime = util.GetPandocRuntime()\n\t\t\tif !util.IsValidPandocBin(pandocRuntime.BinPath) {\n\t\t\t\treturn errors.New(Conf.Language(115))\n\t\t\t}\n\t\t}\n\n\t\ttmpDir := filepath.Join(util.TempDir, \"export\", gulu.Rand.String(7))\n\t\tif bt := getExportBlockTree(id); bt != nil && IsEncryptedBox(bt.BoxID) {\n\t\t\texportID, idErr := newManagedEncryptedExportID()\n\t\t\tif idErr != nil {\n\t\t\t\treturn idErr\n\t\t\t}\n\t\t\ttmpDir = filepath.Join(util.TempDir, \"export\", bt.BoxID, \"docx\", exportID)\n\t\t}\n\t\tif mkdirErr := os.MkdirAll(tmpDir, 0755); mkdirErr != nil {\n\t\t\treturn mkdirErr\n\t\t}\n\t\tdefer os.RemoveAll(tmpDir)\n\t\tname, content := ExportMarkdownHTML(id, tmpDir, true, merge)\n\t\tcontent = strings.ReplaceAll(content, \"  \\n\", \"<br>\\n\")\n","sourceCodeStart":1011,"sourceCodeEnd":1047,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/251596fc0de2f9528c00c224252fd073a99973f4/kernel/model/export.go#L1011-L1047","documentation":"Returned by ExportDocx when, after an initial IsValidPandocBin check fails and util.InitPandoc(Conf.Export.PandocBin) is attempted, the pandoc binary is still invalid. Conf.Language(115) is the message telling the user to configure the Pandoc path in Settings - Export - Pandoc. The check validates that the configured executable exists and runs; Docx export is fully delegated to pandoc, so without a valid binary the export cannot proceed.","triggerScenarios":"POST /api/export/exportDocx (or the UI 'Export - Docx') when Settings - Export - Pandoc executable path is empty, points to a non-existent file, points to a non-executable, or the binary is the wrong architecture. InitPandoc tries to auto-download/bootstrap but that too can fail (no network, wrong platform).","commonSituations":"Fresh install where the user has not configured pandoc. The configured path is stale (pandoc was uninstalled or moved). On macOS, the path changed after a Homebrew upgrade. The binary is for a different architecture (e.g. amd64 on arm64 without Rosetta). Network blocked the auto-download.","solutions":["Install pandoc (https://pandoc.org/installing.html) and set its absolute path in Settings - Export - Pandoc - Path to Pandoc executable.","Verify the binary is executable and matches the OS/architecture: run '<path> --version' in a terminal.","If the path was correct but pandoc was removed, reinstall it and re-set the path.","On macOS after a Homebrew upgrade, update the path (brew --prefix may have changed from /usr/local to /opt/homebrew).","Ensure network access if relying on SiYuan's auto-download of pandoc."],"exampleFix":"// before — empty or wrong pandoc path in config\nConf.Export.PandocBin = \"\"\n// after — set a valid absolute path\nConf.Export.PandocBin = \"/usr/bin/pandoc\" // or \"/opt/homebrew/bin/pandoc\", \"C:\\Program Files\\Pandoc\\pandoc.exe\"","handlingStrategy":"validation","validationCode":"// Validate the configured pandoc binary before exporting to docx\nrt := util.GetPandocRuntime()\nif !util.IsValidPandocBin(rt.BinPath) {\n    util.InitPandoc(Conf.Export.PandocBin)\n    rt = util.GetPandocRuntime()\n}\nif !util.IsValidPandocBin(rt.BinPath) {\n    return errors.New(Conf.Language(115))\n}","typeGuard":null,"tryCatchPattern":"if _, err := model.ExportDocx(id, savePath, false, false); err != nil {\n    if err.Error() == Conf.Language(115) {\n        // prompt user to set Settings - Export - Pandoc path, then retry\n    }\n}","preventionTips":["Install pandoc and set its absolute path in Settings - Export - Pandoc.","Verify '<path> --version' runs in a terminal before configuring.","After OS/pandoc upgrades, re-set the path (Homebrew prefix changes, uninstalls).","Ensure network access for SiYuan's auto-download fallback."],"tags":["pandoc","docx","export","configuration","external-tool"],"backgroundTag":null,"analyzedSha":"251596fc0de2f9528c00c224252fd073a99973f4","analyzedAt":"2026-08-12T21:18:37.123Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}