pandoc convert failed (joined command error and raw output)

Error message

pandoc convert failed (joined command error and raw output)

What it means

ConvertPandoc runs the pandoc binary on a directory and, when pandoc exits non-zero, joins the process error with pandoc's raw combined stdout/stderr output and returns it. The message signals that pandoc itself failed, and the joined value carries the underlying cause plus its raw output.

Solutions

Read the joined error: the second part is pandoc's raw output naming the real failure
Verify the installed pandoc version supports the flags used (pandoc --version)
Check the input directory contents and permissions
Install any missing pandoc dependencies (e.g. LaTeX for PDF exports) and retry

Example fix

// diagnosing
path, err := util.ConvertPandoc(dir, args...)
if err != nil {
  log.Fatalf("pandoc failed: %v", err) // joined: exit error + raw pandoc output
}
// fix: align args with pandoc version
// before: args = ["-f", "gfm+newfeature", ...] // unknown extension on old pandoc
// after:  args = ["-f", "gfm", ...]           // supported by installed pandoc

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check inputs before invoking pandoc
if err := os.Stat(dir); err != nil {
  return fmt.Errorf("convert input dir missing: %w", err)
}

Try / catch

path, err := util.ConvertPandoc(dir, args...)
if err != nil {
  // err is errors.Join(exitErr, rawOutput) — log both parts
  logging.LogErrorf("pandoc conversion failed for %s: %v", dir, err)
  return fmt.Errorf("pandoc conversion failed: %w", err)
}

Prevention

Match pandoc CLI flags to the installed pandoc version
Validate input directory contents and permissions before conversion
Install pandoc's optional dependencies (e.g. LaTeX) for PDF flows
Capture and inspect pandoc output in logs to pinpoint the real cause

When it happens

Trigger: pandoc.CombinedOutput() returns a non-zero exit status while converting a document — e.g. unsupported format flags, unreadable input files in the target directory, or malformed markdown inputs.

Common situations: Passing args unsupported by the installed pandoc version; input directory containing files pandoc cannot parse; pandoc failing due to missing LaTeX for PDF-related conversions; file permission problems in the working directory.

Related errors

AI-assisted analysis of siyuan-note/siyuan@9f775e8a12 (2026-09-19). Data as JSON: /api/errors/b76538b1a23a55b3. Report an issue: GitHub.

Appendix: source

Thrown at kernel/util/pandoc.go:53

func ConvertPandoc(dir string, args ...string) (path string, err error) {
	pandocBinPath := GetPandocRuntime().BinPath
	if "" == pandocBinPath || ContainerStd != Container {
		err = ErrPandocNotFound
		return
	}

	pandoc := exec.Command(pandocBinPath, args...)
	gulu.CmdAttr(pandoc)
	path = filepath.Join("temp", "convert", "pandoc", dir)
	absPath := filepath.Join(WorkspaceDir, path)
	if err = os.MkdirAll(absPath, 0755); err != nil {
		logging.LogErrorf("mkdir [%s] failed: [%s]", absPath, err)
		return
	}
	pandoc.Dir = absPath
	output, err := pandoc.CombinedOutput()
	if err != nil {
		err = errors.Join(err, errors.New(string(output)))
		logging.LogErrorf("pandoc convert output failed: %s", err)
		return
	}
	path = "/" + filepath.ToSlash(path)
	return
}

func Pandoc(from, to, o, content string) (err error) {
	if "" == from || "" == to || "md" == to {
		if err = gulu.File.WriteFileSafer(o, []byte(content), 0644); err != nil {
			logging.LogErrorf("write export markdown file [%s] failed: %s", o, err)
		}
		return
	}

	pandocBinPath := GetPandocRuntime().BinPath
	if "" == pandocBinPath || ContainerStd != Container {
		err = ErrPandocNotFound

View on GitHub (pinned to 9f775e8a12)