Tencent/WeKnora · error

wiki page references unknown folder %q

Error message

wiki page references unknown folder %q

What it means

applyFolderToPage resolves a page's FolderID via repo.GetFolderByID. If the repository reports ErrWikiFolderNotFound, the service returns 'wiki page references unknown folder %q' — the page points at a folder that doesn't exist in that KB. It is a referential-integrity validation error, deliberately distinct from generic storage errors.

Source

Thrown at internal/application/service/wiki_page.go:1393

	return types.CleanWikiCategoryPath(strings.Split(path, "/"))
}

// applyFolderToPage refreshes a page's derived category_path cache from its
// authoritative FolderID. Root ("") clears the path. A folder id that does not
// resolve is treated as a hard error so we never silently misplace a page.
func (s *wikiPageService) applyFolderToPage(ctx context.Context, page *types.WikiPage) error {
	if page == nil {
		return nil
	}
	if strings.TrimSpace(page.FolderID) == "" {
		page.FolderID = ""
		page.CategoryPath = nil
		return nil
	}
	folder, err := s.repo.GetFolderByID(ctx, page.KnowledgeBaseID, page.FolderID)
	if err != nil {
		if errors.Is(err, repository.ErrWikiFolderNotFound) {
			return fmt.Errorf("wiki page references unknown folder %q", page.FolderID)
		}
		return fmt.Errorf("resolve page folder: %w", err)
	}
	page.CategoryPath = types.StringArray(wikiFolderSegments(folder.Path))
	return nil
}

// GetFolder retrieves a single folder by id.
func (s *wikiPageService) GetFolder(ctx context.Context, kbID string, id string) (*types.WikiFolder, error) {
	return s.repo.GetFolderByID(ctx, kbID, id)
}

// ListChildFolders returns the direct children of parentID for a tree view
// scoped to pageTypes. PageCount is recursive (the folder's whole subtree) so
// a parent reflects everything filed beneath it. A folder is shown when its
// subtree holds a page matching pageTypes. Wholly-empty folders (no pages of
// any type underneath) are only listed when multiple types are requested —
// the merged knowledge view — so single-type tabs like summary do not surface

View on GitHub (pinned to 988cbb0330)

Solutions

1. Fetch the current folder list for the KB and pass a valid FolderID (or clear FolderID entirely).
2. Check whether the folder was deleted by another user and choose a new parent folder.
3. Ensure the FolderID belongs to the same knowledge base as the page.
4. Use FindOrCreateFolderPath to resolve a category path to a guaranteed-valid folder instead of raw IDs.

Example fix

// before
page.FolderID = oldFolderID // folder since deleted
svc.UpdatePage(ctx, page)
// after
folder, err := svc.FindOrCreateFolderPath(ctx, kbID, []string{"Docs", "Guides"})
if err != nil { return err }
page.FolderID = folder.ID
svc.UpdatePage(ctx, page)

folders, err := svc.ListFolders(ctx, kbID)
if err != nil { return err }
known := make(map[string]bool, len(folders))
for _, f := range folders { known[f.ID] = true }
if page.FolderID != "" && !known[page.FolderID] {
    page.FolderID = "" // clear stale reference instead of failing
}

func folderExists(folderID string, folders []*types.WikiFolder) bool {
    if folderID == "" { return true }
    for _, f := range folders { if f.ID == folderID { return true } }
    return false
}

_, err := svc.UpdatePage(ctx, page)
if err != nil && strings.Contains(err.Error(), "references unknown folder") {
    page.FolderID = "" // drop stale folder, keep the page save
    _, err = svc.UpdatePage(ctx, page)
}

When it happens

Trigger: CreatePage/UpdatePage/MovePage with a FolderID that no longer exists (or never existed) in page.KnowledgeBaseID — deleted folder, folder from another KB, or a fabricated/garbage ID.

Common situations: Folders deleted while clients held stale folder IDs in cached forms; copying pages between knowledge bases without remapping FolderID; frontend sending empty-string vs nil handling bugs; concurrent folder deletion and page move.

Related errors

• folder name %q must not contain a path separator
• invite code has expired
• join request not found
• failed to retrieve: %s
• opensearch: index not found

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/e73e34af88a3a73b. Report an issue: GitHub.