siyuan-note/siyuan · error

unsupported renderDocRef query mode [%s]

Error message

unsupported renderDocRef query mode [%s]

What it means

renderDocRef supports exactly two query modes: "children" and "path". Any other mode string reaches the default branch of the switch and fails with "unsupported renderDocRef query mode [<mode>]". This is an explicit enumeration guard rather than silent fallback.

Source

Thrown at kernel/model/template_doc_tree.go:274

				return node.Children, nil
			}
		}
		return []*TemplateDocTreeNode{}, nil
	case "path":
		hPath, ok := value.(string)
		if !ok {
			return "", errors.New("renderDocRef path target must be a document path")
		}
		requestedPath := path.Clean(hPath)
		for _, node := range flattenTemplateDocTreeNodes0(collector.nodes) {
			relativePath := strings.TrimPrefix(node.HPath, collector.rootHPath)
			if node.HPath == requestedPath || relativePath == requestedPath {
				return fmt.Sprintf("((%s %q))", node.RootID, node.HPath), nil
			}
		}
		return "", nil
	default:
		return nil, fmt.Errorf("unsupported renderDocRef query mode [%s]", mode)
	}
}

func flattenTemplateDocTreeNodes0(nodes []*TemplateDocTreeNode) (ret []*TemplateDocTreeNode) {
	for _, node := range nodes {
		ret = append(ret, node)
		ret = append(ret, flattenTemplateDocTreeNodes0(node.Children)...)
	}
	return
}

func (collector *templateDocTreeCollector) validateLocations() error {
	box := Conf.Box(collector.boxID)
	if nil == box {
		return ErrBoxNotFound
	}
	allowCreateDeeper := nil != Conf.FileTree && Conf.FileTree.AllowCreateDeeper
	for _, node := range flattenTemplateDocTreeNodes0(collector.nodes) {

View on GitHub (pinned to 8641553a1f)

Solutions

1. Use only "children" or "path" as the mode string, lowercase.
2. If you need other lookups (parent/siblings), use node fields from the children result (each node carries ParentID/RootID/HPath).
3. Check spelling and case of the mode argument.

Example fix

// before
renderDocRef("Children", rootID)
// after
renderDocRef("children", rootID)

const MODES = ["children", "path"];
if (!MODES.includes(mode)) throw new Error(`unsupported renderDocRef mode: ${mode}`);

const isRenderDocRefMode = (v) => v === "children" || v === "path";

try {
  const out = renderDocRef(mode, value);
} catch (e) {
  if (/unsupported renderDocRef query mode/.test(String(e))) {
    // map legacy mode names to children/path before retrying
  }
}

When it happens

Trigger: Calling renderDocRef("parent", ...), renderDocRef("siblings", ...), renderDocRef("Children", ...) (case-sensitive), or a misspelled mode like renderDocRef("child", ...).

Common situations: Assuming the API supports more query modes than implemented; capitalization typos; copying pseudo-code from docs or issues describing wished-for modes.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• renderDocRef children target must be a document ID
• renderDocRef path target must be a document path
• Parse template failed: %s
• parse tree [%s] failed
• database [%s] template field [%s] rendering failed: %s

AI-assisted analysis of siyuan-note/siyuan@8641553a1f (2026-09-11). Data as JSON: /api/errors/92bddb6e27bfaaf1. Report an issue: GitHub.