{"record":{"id":"316897b5b8a9804f","repo":"siyuan-note/siyuan","slug":"output-is-required-for-docx","errorCode":null,"errorMessage":"--output is required for docx","messagePattern":"--output is required for docx","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kernel/cli/cmd/export.go","lineNumber":115,"sourceCode":"\t\tif output != \"\" {\n\t\t\treturn os.WriteFile(output, []byte(html), 0644)\n\t\t}\n\t\tfmt.Print(html)\n\t\treturn nil\n\t},\n}\n\nvar exportDocxCmd = &cobra.Command{\n\tUse:   \"docx --id <id> --output <file>\",\n\tShort: \"Export as Word (.docx)\",\n\tRunE: func(cmd *cobra.Command, args []string) error {\n\t\tid, _ := cmd.Flags().GetString(\"id\")\n\t\toutput, _ := cmd.Flags().GetString(\"output\")\n\t\tif id == \"\" {\n\t\t\treturn fmt.Errorf(\"--id is required\")\n\t\t}\n\t\tif output == \"\" {\n\t\t\treturn fmt.Errorf(\"--output is required for docx\")\n\t\t}\n\n\t\tif dryRun {\n\t\t\tfmt.Printf(\"[dry-run] Would export docx for document %s to %s\\n\", id, output)\n\t\t\treturn nil\n\t\t}\n\n\t\tfullPath, err := model.ExportDocx(id, output, false, false)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tfmt.Println(fullPath)\n\t\treturn nil\n\t},\n}\n\nvar exportSYCmd = &cobra.Command{\n\tUse:   \"sy --id <id> [--output <dir>]\",","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/251596fc0de2f9528c00c224252fd073a99973f4/kernel/cli/cmd/export.go#L97-L133","documentation":"The `export docx` subcommand additionally requires the --output flag (a file path) because Word export produces a binary .docx that cannot be streamed to stdout. The handler checks --id first, then --output, returning this error when --output is empty, before the dry-run check and before model.ExportDocx. This is the key difference from the md/html/preview subcommands which treat --output as optional.","triggerScenarios":"Running `siyuan export docx --id <id>` without --output; passing `--output \"\"`; scripting with an unset output path variable; misspelling the flag; expecting docx content on stdout.","commonSituations":"Assuming --output is optional like the other export subcommands; forgetting the destination path; pointing --output at an unwritable directory (caught later as a write error, not here); shell variable empty for an iteration.","solutions":["Supply an output file path: `siyuan export docx --id <id> --output /path/to/file.docx`.","Ensure the parent directory exists and is writable.","Guard the output variable in scripts.","Use `--dry-run` to preview before writing.","Verify the flag with `siyuan export docx --help`."],"exampleFix":"// before\nsiyuan export docx --id 20240101000000-abc1234\n// after\nsiyuan export docx --id 20240101000000-abc1234 --output ./notes.docx","handlingStrategy":"validation","validationCode":"[ -n \"$OUT\" ] || { echo '--output is required for docx' >&2; exit 2; }\nmkdir -p \"$(dirname \"$OUT\")\"\nsiyuan export docx --id \"$DOC_ID\" --output \"$OUT\"","typeGuard":null,"tryCatchPattern":"if ! siyuan export docx --id \"$DOC_ID\" --output \"$OUT\" 2>err.txt; then\n  grep -q 'output is required' err.txt && echo \"docx needs --output <file.docx>\" >&2\n  exit 1\nfi","preventionTips":["Always pass --output for docx; it cannot stream to stdout.","Ensure the parent directory exists and is writable before invoking.","Use `set -u` to catch unset output path variables."],"tags":["cli","cobra","flag-validation","export","docx","filesystem","go"],"backgroundTag":null,"analyzedSha":"251596fc0de2f9528c00c224252fd073a99973f4","analyzedAt":"2026-08-12T21:18:37.123Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}