siyuan-note/siyuan · error

export failed: empty content

Error message

export failed: empty content

What it means

writeExportContent delivers the exported text content: writes it to `output` when provided, otherwise prints it to stdout. It returns this error when the exported content string is empty, since writing/echoing nothing is never a useful result and would silently clobber the output file with a zero-byte file.

Solutions

1. Verify the document ID is valid and the document has content before exporting.
2. Check the return of the underlying export call and propagate its error instead of discarding it.
3. Do not reuse the same output path on failure — this guard exists so an existing file is preserved; inspect rather than overwrite.
4. If you intentionally need to write empty content, write the file yourself with os.WriteFile instead of using this helper.

Example fix

// before
content, _ := renderDocHTML(id)
err := writeExportContent(content, out) // error: empty content

// after
content, err := renderDocHTML(id)
if err != nil {
    return err
}
if content == "" {
    return fmt.Errorf("document %s rendered to empty content", id)
}
return writeExportContent(content, out)

content, err := renderDocHTML(id)
if err != nil {
    return err
}
if content == "" {
    return fmt.Errorf("empty render output for %s", id)
}
return writeExportContent(content, output)

if err := writeExportContent(content, output); err != nil {
    if strings.Contains(err.Error(), "empty content") {
        // do not overwrite output; inspect the export source first
    }
    return err
}

When it happens

Trigger: The HTML/preview/markdown export routine returned an empty string (failed render, missing document) and writeExportContent is called with content=""; also invoked directly in tests with an empty string (TestWriteExportContentPreservesExistingOutputOnFailure).

Common situations: Exporting a document that no longer exists or renders to nothing; a pipeline where an earlier step swallowed the export result; misconfigured export options producing empty output.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• export failed: empty artifact path
• --id is required
• --output is required for docx
• appearance files not found at
• --attr is required (format: name=value)

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

Appendix: source

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

	exportMdZipCmd.Flags().String("id", "", "block ID")
	exportMdZipCmd.Flags().String("output", "", "output file path (default: print temp path)")

	exportDataCmd.Flags().String("output", "", "output file path (default: print temp path)")

	rootCmd.AddCommand(exportCmd)
	exportCmd.AddCommand(exportMdCmd)
	exportCmd.AddCommand(exportHTMLCmd)
	exportCmd.AddCommand(exportPreviewCmd)
	exportCmd.AddCommand(exportDocxCmd)
	exportCmd.AddCommand(exportSYCmd)
	exportCmd.AddCommand(exportMdZipCmd)
	exportCmd.AddCommand(exportDataCmd)
}

func writeExportContent(content, output string) error {
	if content == "" {
		return fmt.Errorf("export failed: empty content")
	}
	if output != "" {
		return os.WriteFile(output, []byte(content), 0644)
	}
	fmt.Print(content)
	return nil
}

View on GitHub (pinned to 9f775e8a12)