siyuan-note/siyuan · error

document not found or empty

Error message

document not found or empty

What it means

The `block info` CLI command fails when `filesys.StatTree(id)` returns nil, meaning no document tree exists for the given --id or the document is empty. The CLI requires a resolvable document before it can report statistics.

Solutions

1. Verify the --id is a valid document ID from an existing notebook in the current workspace (check the .sy filename under data/<notebook>/).
2. List documents to find the correct ID (e.g. inspect data/<notebookID>/*.sy files) and retry with the correct document ID.
3. Confirm the kernel workspace is correct so StatTree looks in the right data directory.
4. If the document exists but is empty, add content to it or use a non-empty document.

Example fix

// before
siyuan block info --id 20240101120000-abcdefg
// after
siyuan block info --id 20240101120000-h1x2y3z  # actual .sy doc ID in the workspace

if [ -z "$DOC_ID" ]; then echo "--id required" >&2; exit 1; fi
siyuan block info --id "$DOC_ID" || { echo "document $DOC_ID not found in workspace" >&2; exit 1; }

out=$(siyuan block info --id "$DOC_ID" 2>&1) || { echo "$out"; exit 1; }

When it happens

Trigger: Running `siyuan block info --id <id>` where the id is not an existing document ID (typo, wrong notebook, block deleted) or points to a document whose tree fails to load / is empty.

Common situations: Copy-pasting a block ID instead of a document ID; using an ID from a notebook not present in the workspace; the document was deleted or renamed by another session; passing a synthetic/invalid ID.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• document not found
• block not found
• database not found
• document not found or has no headings
• --id is required

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

Appendix: source

Thrown at kernel/cli/cmd/block.go:168

		if mode == "" {
			mode = "md"
		}
		fmt.Print(model.GetBlockKramdown(id, mode))
		return nil
	},
}

var blockStatCmd = &cobra.Command{
	Use:   "stat --id <id>",
	Short: "Get block content statistics",
	RunE: func(cmd *cobra.Command, args []string) error {
		id, _ := cmd.Flags().GetString("id")
		if id == "" {
			return fmt.Errorf("--id is required")
		}
		stat := filesys.StatTree(id)
		if stat == nil {
			return fmt.Errorf("document not found or empty")
		}
		switch outputFormat {
		case "json":
			data, _ := json.MarshalIndent(stat, "", "  ")
			fmt.Println(string(data))
		default:
			fmt.Printf("Characters: %d\n", stat.RuneCount)
			fmt.Printf("Words:      %d\n", stat.WordCount)
			fmt.Printf("Blocks:     %d\n", stat.BlockCount)
			fmt.Printf("Links:      %d\n", stat.LinkCount)
			fmt.Printf("Images:     %d\n", stat.ImageCount)
			fmt.Printf("Refs:       %d\n", stat.RefCount)
		}
		return nil
	},
}

// ─── Write ─────────────────────────────────────────────────────────────────────

View on GitHub (pinned to 9f775e8a12)