siyuan-note/siyuan · error

export failed: empty artifact path

Error message

export failed: empty artifact path

What it means

materializeExportArtifact is the shared helper behind `export sy`, `export md-zip`, and `export data`: it takes the zip path returned by the model export routine, acquires an artifact lease on it, and either copies it to `--output` or returns the leased path. Its first statement asserts the path is non-empty. Crucially, the callers discard the error return of model.ExportPandocConvertZip with `_`, so when the underlying export fails (e.g. pandoc unavailable, invalid document) and yields an empty path, this guard is what surfaces the problem. It therefore indicates a failed or silently-short-circuited export, not a flag mistake.

Source

Thrown at kernel/cli/cmd/export.go:226

		zipPath, err := model.ExportData()
		if err != nil {
			return err
		}
		resultPath, err := materializeExportArtifact(zipPath, output)
		if err != nil {
			return err
		}
		if output == "" {
			fmt.Println(resultPath)
		}
		return nil
	},
}

func materializeExportArtifact(exportPath, output string) (resultPath string, err error) {
	if exportPath == "" {
		return "", fmt.Errorf("export failed: empty artifact path")
	}
	lease, err := model.AcquireExportArtifactLease(exportPath)
	if err != nil {
		return "", err
	}
	defer model.ReleaseExportArtifactLease(lease.ID)

	if output == "" {
		return lease.Path, nil
	}
	if err = filelock.Copy(lease.Path, output); err != nil {
		return "", err
	}
	return output, nil
}

func init() {
	exportMdCmd.Flags().String("id", "", "block ID")

View on GitHub (pinned to afa823b6b4)

Solutions

1. Confirm the document ID is valid: open it in the UI or find it with `siyuan document search`, then retry
2. Check the kernel log for the real underlying failure — the returned error was discarded before this guard fired
3. For md-zip/sy exports, verify pandoc is installed and on PATH (`pandoc --version`) since the conversion zip goes through it
4. Check the workspace temp/export directories are writable and not full
5. If it reproduces on a valid ID with a healthy environment, report it as a bug: an export returning an empty path without an error is a kernel defect (the CLI should propagate model.ExportPandocConvertZip's error instead of discarding it)

Example fix

// before (kernel/cli/cmd/export.go)
_, zipPath := model.ExportPandocConvertZip([]string{id}, "", ".sy")
resultPath, err := materializeExportArtifact(zipPath, output)
// after
if _, zipPath := model.ExportPandocConvertZip([]string{id}, "", ".sy"); zipPath == "" {
    return fmt.Errorf("sy export produced no artifact for document %s", id)
}
// or capture and check the discarded error return

run_export() {
  siyuan export sy --id "$1" --output "$2" 2>err.txt
}
if ! run_export "$ID" out.zip; then
  sleep 2
  if ! run_export "$ID" out.zip; then
    echo "export produced no artifact; check kernel log and pandoc" >&2; exit 1
  fi
fi

When it happens

Trigger: Running `siyuan export sy --id <id>` or `siyuan export md-zip --id <id>` (with or without `--output`) when model.ExportPandocConvertZip returns an empty zip path; likewise `siyuan export data` when model.ExportData returns an empty path. Typical root causes: nonexistent/deleted document ID, pandoc not installed or failing during conversion, or an export routine that aborted without propagating its error.

Common situations: Exporting an ID captured before the document was deleted or renamed; environments where the pandoc binary is missing from PATH (md-zip and sy conversion depend on it); kernel versions where the export routine swallows errors; full or read-only temp/export directories.

Related errors

• block write failed: empty block ID
• --id is required
• --output is required for docx
• CLI does not support encrypted notebook [%s]
• AI editor model returned nil stream

AI-assisted analysis of siyuan-note/siyuan@afa823b6b4 (2026-08-18). Data as JSON: /api/errors/7a30d1038362de89. Report an issue: GitHub.