siyuan-note/siyuan · error

keyword is required

Error message

keyword is required

What it means

The `document search` cobra subcommand takes a positional keyword argument (Args: cobra.MinimumNArgs(1) already guarantees at least one arg). Inside RunE, the handler reads args[0] and returns this error when the keyword is the empty string — i.e. the user passed an explicitly empty argument like `siyuan document search ""`. The MinimumNArgs guard cannot catch an empty-valued positional, so this check covers that gap before calling model.SearchDocs.

Source

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

		if "/" == targetHPath {
			return "/", nil
		}
	}

	if targetPath, found := lookup(targetHPath); found {
		return targetPath, nil
	}
	return "", fmt.Errorf("target human-readable path not found: %s", targetHPath)
}

var documentSearchCmd = &cobra.Command{
	Use:   "search <keyword>",
	Short: "Search documents by keyword",
	Args:  cobra.MinimumNArgs(1),
	RunE: func(cmd *cobra.Command, args []string) error {
		keyword := args[0]
		if keyword == "" {
			return fmt.Errorf("keyword is required")
		}
		docs := model.SearchDocs(keyword, false, nil)
		switch outputFormat {
		case "json":
			data, _ := json.MarshalIndent(docs, "", "  ")
			fmt.Println(string(data))
		default:
			if len(docs) == 0 {
				fmt.Println("No documents found.")
				return nil
			}
			w := tabwriter.NewWriter(os.Stdout, 0, 0, 2, ' ', 0)
			fmt.Fprintln(w, "TYPE\tID\tNAME\tHPATH")
			for _, d := range docs {
				typ, id, name := documentSearchDisplayFields(d)
				fmt.Fprintf(w, "%s\t%s\t%s\t%s\n", typ, id, name, d["hPath"])
			}
			w.Flush()

View on GitHub (pinned to 251596fc0d)

Solutions

1. Pass a non-empty keyword: `siyuan document search "meeting"`.
2. In scripts, skip empty values: `[ -n "$kw" ] && siyuan document search "$kw"`.
3. Trim and validate the keyword before invoking.
4. If reading keywords from a file, filter blank lines first.

Example fix

// before
siyuan document search "$KEYWORD"   # KEYWORD unset -> ""
// after
[ -n "$KEYWORD" ] && siyuan document search "$KEYWORD"

# skip empty keywords when iterating
[ -n "$KEYWORD" ] || { echo 'keyword is required' >&2; exit 2; }
siyuan document search "$KEYWORD"

// Go: guard the positional before calling SearchDocs
func nonEmptyKeyword(args []string) (string, bool) {
    if len(args) == 0 || args[0] == "" { return "", false }
    return args[0], true
}

if ! siyuan document search "$KEYWORD" 2>err.txt; then
  grep -q 'keyword is required' err.txt && echo "pass a non-empty keyword" >&2
  exit 1
fi

When it happens

Trigger: Running `siyuan document search ""` with an explicit empty string argument; passing an unset shell variable that expands to empty: `siyuan document search "$UNSET"`; quoting an empty expansion; a script loop where the keyword variable is empty for one iteration.

Common situations: Scripting a search over a list where one element is empty; reading keywords from a file with a blank line; an env variable that was never set; assuming the command errors on zero args only (it does) but not realizing `""` satisfies MinimumNArgs(1).

Related errors

• invalid JSON: %s
• --notebook is required
• --title is required
• --id is required
• document not found: %s

AI-assisted analysis of siyuan-note/siyuan@251596fc0d (2026-08-12). Data as JSON: /api/errors/f6fb67e2c15cb001. Report an issue: GitHub.