Please configure [Settings - Export - Pandoc - Path to Pando

Error message

Please configure [Settings - Export - Pandoc - Path to Pandoc executable] first

What it means

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.

Source

Thrown at kernel/model/export.go:1029

		if footnotesDefBlock := tree.Root.ChildByType(ast.NodeFootnotesDefBlock); nil != footnotesDefBlock {
			footnotesDefBlock.Unlink()
		}
		return nil
	}); exportErr != nil {
		logging.LogErrorf("export preview [%s] failed: %s", id, exportErr)
		return
	}
	return
}

func ExportDocx(id, savePath string, removeAssets, merge bool) (fullPath string, err error) {
	err = withExportReadLockByBlockID(id, func() error {
		pandocRuntime := util.GetPandocRuntime()
		if !util.IsValidPandocBin(pandocRuntime.BinPath) {
			util.InitPandoc(Conf.Export.PandocBin)
			pandocRuntime = util.GetPandocRuntime()
			if !util.IsValidPandocBin(pandocRuntime.BinPath) {
				return errors.New(Conf.Language(115))
			}
		}

		tmpDir := filepath.Join(util.TempDir, "export", gulu.Rand.String(7))
		if bt := getExportBlockTree(id); bt != nil && IsEncryptedBox(bt.BoxID) {
			exportID, idErr := newManagedEncryptedExportID()
			if idErr != nil {
				return idErr
			}
			tmpDir = filepath.Join(util.TempDir, "export", bt.BoxID, "docx", exportID)
		}
		if mkdirErr := os.MkdirAll(tmpDir, 0755); mkdirErr != nil {
			return mkdirErr
		}
		defer os.RemoveAll(tmpDir)
		name, content := ExportMarkdownHTML(id, tmpDir, true, merge)
		content = strings.ReplaceAll(content, "  \n", "<br>\n")

View on GitHub (pinned to 251596fc0d)

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.

Example fix

// before — empty or wrong pandoc path in config
Conf.Export.PandocBin = ""
// after — set a valid absolute path
Conf.Export.PandocBin = "/usr/bin/pandoc" // or "/opt/homebrew/bin/pandoc", "C:\Program Files\Pandoc\pandoc.exe"

Defensive patterns

Strategy: validation

Validate before calling

// Validate the configured pandoc binary before exporting to docx
rt := util.GetPandocRuntime()
if !util.IsValidPandocBin(rt.BinPath) {
    util.InitPandoc(Conf.Export.PandocBin)
    rt = util.GetPandocRuntime()
}
if !util.IsValidPandocBin(rt.BinPath) {
    return errors.New(Conf.Language(115))
}

Try / catch

if _, err := model.ExportDocx(id, savePath, false, false); err != nil {
    if err.Error() == Conf.Language(115) {
        // prompt user to set Settings - Export - Pandoc path, then retry
    }
}

Prevention

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.

When it happens

Trigger: 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).

Common situations: 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.

Related errors

AI-assisted analysis of siyuan-note/siyuan@251596fc0d (2026-08-12). Data as JSON: /api/errors/7fbe6f3ab6bd153a. Report an issue: GitHub.