What causes "write pandoc docx filter: %w" in siyuan-note/siyuan?

Check that the export directory exists and is writable by the SiYuan process (os.Getuid / permissions on the dir)

write pandoc docx filter: %w

Error message

write pandoc docx filter: %w

What it means

writePandocDocxFilter extracts the embedded pandoc_docx_filter.lua (via go:embed) to a working directory before a DOCX export runs, so pandoc can apply SiYuan's Lua filter. The error wraps the os.WriteFile failure, meaning the temp/export directory could not be written to. It is a low-level filesystem failure surfaced during document export, not a pandoc or Lua problem.

Source

Thrown at kernel/model/pandoc_docx_filter.go:34

package model

import (
	_ "embed"
	"fmt"
	"os"
	"path/filepath"
)

const pandocDocxFilterName = "siyuan-docx-filter.lua"

//go:embed pandoc_docx_filter.lua
var pandocDocxFilter []byte

func writePandocDocxFilter(dir string) (string, error) {
	filterPath := filepath.Join(dir, pandocDocxFilterName)
	if err := os.WriteFile(filterPath, pandocDocxFilter, 0600); err != nil {
		return "", fmt.Errorf("write pandoc docx filter: %w", err)
	}
	return filterPath, nil
}

func appendBuiltinPandocDocxFilter(args []string, filterPath string) []string {
	return append(args, "--lua-filter", filterPath)
}

View on GitHub (pinned to 8641553a1f)

Solutions

Check that the export directory exists and is writable by the SiYuan process (os.Getuid / permissions on the dir)
Free disk space or raise the quota on the volume holding the export dir
Re-run the export; if the dir was transiently removed, ensure no cleanup job races with export
Run SiYuan outside restricted sandboxes/AV policies that block file creation

Example fix

// before: assuming export dir is always writable
filterPath, err := writePandocDocxFilter(exportDir)
// after: verify the dir is writable first
if info, err := os.Stat(exportDir); err != nil || !info.IsDir() {
    return fmt.Errorf("export dir unavailable: %w", err)
}
filterPath, err := writePandocDocxFilter(exportDir)

Defensive patterns

Strategy: try-catch

Validate before calling

if info, err := os.Stat(exportDir); err != nil || !info.IsDir() {
    return fmt.Errorf("export dir %s unavailable", exportDir)
}
if f, err := os.CreateTemp(exportDir, ".probe"); err != nil {
    return fmt.Errorf("export dir %s not writable: %w", exportDir, err)
} else { f.Close(); os.Remove(f.Name()) }

Try / catch

filterPath, err := model.WritePandocDocxFilter(dir)
if err != nil {
    var pathErr *os.PathError
    if errors.As(err, &pathErr) {
        return fmt.Errorf("cannot write filter to %s: %v (check permissions/disk)", pathErr.Path, pathErr.Err)
    }
    return err
}

Prevention

Probe writability of the export directory before starting DOCX export
Monitor disk space on the volume hosting the workspace
Exclude the workspace and temp dirs from AV/sandbox write blocking
Keep SiYuan running with write access to its own workspace

When it happens

Trigger: Calling the DOCX export path (model/export via pandoc conversion) when the target directory is read-only, was deleted between creation and the WriteFile call, is on a full disk, or the process lacks write permission for the filter file.

Common situations: Running the kernel from a read-only volume or with restricted permissions; disk quota/full disk during a large export; antivirus or sandboxing blocking creation of new files in the export dir; exporting to a directory removed by concurrent cleanup.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

AI-assisted analysis of siyuan-note/siyuan@8641553a1f (2026-09-11). Data as JSON: /api/errors/53aca078b7436ba5. Report an issue: GitHub.