siyuan-note/siyuan · error

document not found or has no headings

Error message

document not found or has no headings

What it means

Result-empty guard in outlineGet: model.Outline succeeded but returned no heading paths, which means the given document ID either does not resolve to an existing document or the document contains no headings at all. Not an argument error — check the document ID and its content.

Solutions

1. Verify the document exists and the id is a block/document id, not a notebook id
2. Add at least one heading to the document if it is empty of headings
3. Ensure the notebook is open so the document is indexed
4. Confirm the workspace matches where the document lives

Example fix

// before
siyuan outline get --id <id-of-notebook>
// after
siyuan outline get --id 20240101120000-docid12

siyuan outline get --id "$DOC_ID" || { echo "document missing or has no headings"; }

const outlineOk = (paths) => Array.isArray(paths) && paths.length > 0;

try { run(`siyuan outline get --id ${docId}`); } catch (e) { if (/no headings/.test(e.message)) console.warn("Doc has no headings; skipping outline"); }

When it happens

Trigger: Passing a nonexistent document id, a document with zero headings, or a closed/unloaded document so the outline index returns nothing.

Common situations: Wrong workspace, document id vs notebook id confusion, or genuinely heading-less documents.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• block not found
• database not found
• document not found or empty
• document not found
• --id is required

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

Appendix: source

Thrown at kernel/cli/cmd/outline.go:47

var outlineCmd = &cobra.Command{
	Use:   "outline",
	Short: "Document outline (heading tree)",
}

var outlineGetCmd = &cobra.Command{
	Use:   "get --id <id>",
	Short: "Get document outline",
	RunE: func(cmd *cobra.Command, args []string) error {
		id, _ := cmd.Flags().GetString("id")
		if id == "" {
			return fmt.Errorf("--id is required")
		}
		paths, err := model.Outline(id, false)
		if err != nil {
			return err
		}
		if len(paths) == 0 {
			return fmt.Errorf("document not found or has no headings")
		}
		switch outputFormat {
		case "json":
			data, _ := json.MarshalIndent(paths, "", "  ")
			fmt.Println(string(data))
		default:
			var sb strings.Builder
			sb.WriteString(fmt.Sprintf("Document outline (%d headings):\n\n", countOutlineHeadings(paths)))
			for _, p := range paths {
				writeOutlinePath(&sb, p, 0)
			}
			fmt.Print(sb.String())
		}
		return nil
	},
}

func countOutlineHeadings(paths []*model.Path) int {

View on GitHub (pinned to 9f775e8a12)