siyuan-note/siyuan · error

Cannot create a file starting with .

Error message

Cannot create a file starting with .

What it means

Thrown by validateCreateDoc when the path's base filename starts with a dot ('.'). Conf.Language(13) = 'Cannot create a file starting with .'. Dotfiles are hidden files on Unix and reserved names on Windows; SiYuan blocks them to prevent hidden document files, filesystem inconsistencies, and OS-level access issues.

Source

Thrown at kernel/model/file.go:2264

	if 512 < utf8.RuneCountInString(title) {
		// 限制笔记本名和文档名最大长度为 `512` https://github.com/siyuan-note/siyuan/issues/6299
		return nil, errors.New(Conf.Language(106))
	}

	isEmpty := false
	if "" == title {
		title = Conf.Language(16)
		isEmpty = true
	} else if titleEmpty {
		isEmpty = true
	}

	baseName := strings.TrimSpace(path.Base(p))
	if "" == util.GetTreeID(baseName) {
		return nil, errors.New(Conf.Language(16))
	}
	if strings.HasPrefix(baseName, ".") {
		return nil, errors.New(Conf.Language(13))
	}

	box, boxErr := getOpenedBox(boxID)
	if nil != boxErr {
		return nil, boxErr
	}

	folder := path.Dir(p)
	hPath := "/" + title
	if "/" != folder {
		parentID := path.Base(folder)
		parentTree, loadErr := LoadTreeByBlockID(parentID)
		if nil != loadErr {
			logging.LogErrorf("get parent tree [%s] failed", parentID)
			return nil, ErrBlockNotFound
		}
		parentPath := strings.TrimSuffix(parentTree.Path, ".sy")
		if parentTree.Box != boxID || cleanBoxDocDir(parentPath) != cleanBoxDocDir(folder) {

View on GitHub (pinned to 251596fc0d)

Solutions

1. Strip any leading '.' from the path's base name before creating the document.
2. Ensure path construction logic doesn't prepend dots (common in template string bugs).
3. Pre-validate: check !strings.HasPrefix(path.Base(p), ".") before calling create functions.
4. If a dotfile-named document was intended for hiding, use SiYuan's bookmark or hidden-bookmark IAL instead.

Example fix

// before
p := "/notes/.20240101120000-abcdefg.sy"
err := model.ValidateCreateDoc(boxID, p, title)

// after
base := path.Base(p)
if strings.HasPrefix(base, ".") {
    base = strings.TrimPrefix(base, ".")
    p = path.Join(path.Dir(p), base)
}
err := model.ValidateCreateDoc(boxID, p, title)

// Pre-check: ensure path base name doesn't start with a dot
baseName := strings.TrimSpace(path.Base(p))
if strings.HasPrefix(baseName, ".") {
    baseName = strings.TrimPrefix(baseName, ".")
    p = path.Join(path.Dir(p), baseName)
}

func hasNoLeadingDot(p string) bool {
    baseName := strings.TrimSpace(path.Base(p))
    return !strings.HasPrefix(baseName, ".")
}

When it happens

Trigger: Calling create/validate functions with a path whose base name begins with '.', e.g., '/folder/.20240101-abcdefg.sy' or '/folder/.hidden.sy'. The check at line 2263 uses strings.HasPrefix(baseName, ".").

Common situations: A path is constructed by prepending '.' accidentally (e.g., string concatenation bug). A template or migration generates dotfile-style paths. An imported file had a dot-prefixed name on the source filesystem.

Related errors

• Untitled
• Duplicated filename
• import path is not sub path of import dir
• custom emoji name must not be empty
• not a valid workspace: %s

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