siyuan-note/siyuan · error

keyword is required

Error message

keyword is required

What it means

The `siyuan document search` command takes the keyword as its first positional argument (Args: cobra.MinimumNArgs(1)). This guard fires when args[0] exists but is an empty string, meaning search was called with a quoted empty argument. Without any argument cobra itself rejects the call; with "" the command returns this error before calling model.SearchDocs.

Solutions

1. Provide a non-empty keyword: `siyuan document search <keyword>`
2. Fail fast in the calling script when the search term variable is empty
3. Filter blank entries out of keyword lists before looping over the command

Example fix

// before
document search "$QUERY"   # QUERY may be empty
// after
: "${QUERY:?QUERY must not be empty}"
document search "$QUERY"

if [ -z "${QUERY:-}" ]; then echo "keyword is required" >&2; exit 2; fi
siyuan document search "$QUERY"

When it happens

Trigger: Running `document search ""`; scripts interpolating an empty variable: `document search "$Q"` with Q unset; pipeline stages that pass an empty first field after word splitting.

Common situations: Search terms read from a config or prompt that defaulted to empty; loops over keywords where one entry is blank; forgotten argument that shell quoting turned into an empty string rather than a missing one.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• --av and --ids are required
• --av and --key are required
• --av is required
• --av, --key, --item and --value are required
• --av, --name and --type are required

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

Appendix: source

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

		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 9f775e8a12)