siyuan-note/siyuan · error

--title is required

Error message

--title is required

What it means

After the notebook check, `siyuan document create` validates that a non-empty title was supplied via `--title`. The title is used for model.ValidateCreateDoc and for the new document, so an empty title is rejected with this error before any file is written.

Solutions

1. Pass a non-empty title: `siyuan document create --notebook <notebookID> --title "My document"`
2. Check the source data/variable so empty titles are skipped or defaulted before invoking
3. If the title is intentionally empty, supply a placeholder since the kernel requires one

Example fix

// before
siyuan document create --notebook $NB_ID
// after
siyuan document create --notebook $NB_ID --title "Untitled"

[ -n "$TITLE" ] || { echo "--title is required" >&2; exit 1; }
siyuan document create --notebook "$NB_ID" --title "$TITLE"

When it happens

Trigger: Running `siyuan document create --notebook <notebookID>` without `--title`, or with `--title ""`. Also when a TITLE shell variable is empty due to a failed upstream substitution.

Common situations: Batch-creation scripts reading titles from a data file where a row's title column is empty; forgetting --title while testing the command interactively; passing the title through a variable that was never set.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• --id is required
• --notebook is required
• --av and --ids are required
• --av, --key, --item and --value are required
• --block is required for non-detached rows

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

Appendix: source

Thrown at kernel/cli/cmd/document.go:80

			printDocumentTable(files)
		}
		return nil
	},
}

var documentCreateCmd = &cobra.Command{
	Use:   "create --notebook <id> --title <title>",
	Short: "Create a document",
	RunE: func(cmd *cobra.Command, args []string) error {
		notebook, _ := cmd.Flags().GetString("notebook")
		title, _ := cmd.Flags().GetString("title")
		dir, _ := cmd.Flags().GetString("path")
		markdown, _ := cmd.Flags().GetString("markdown")
		if notebook == "" {
			return fmt.Errorf("--notebook is required")
		}
		if title == "" {
			return fmt.Errorf("--title is required")
		}
		dir = normalizeDocumentCreateParentPath(dir)
		id := ast.NewNodeID()
		docPath := path.Join(dir, id+".sy")
		if err := model.ValidateCreateDoc(notebook, docPath, title); err != nil {
			return formatNotebookWriteError(notebook, err)
		}

		if dryRun {
			fmt.Printf("[dry-run] Would create document \"%s\" in notebook %s\n", title, notebook)
			return nil
		}

		_, err := model.CreateDocByMd(notebook, docPath, title, markdown, nil, nil)
		if err != nil {
			return formatNotebookWriteError(notebook, err)
		}
		model.AppendPushCreateEntry(notebook, docPath)

View on GitHub (pinned to 9f775e8a12)