What causes "failed to resolve wiki page %s in knowledge base %s: %w" in Tencent/WeKnora?

Inspect the wrapped cause with errors.Is/As to identify the underlying repository error

failed to resolve wiki page %s in knowledge base %s: %w

Error message

failed to resolve wiki page %s in knowledge base %s: %w

What it means

While probing each allowed knowledge-base scope with GetPageBySlug, the resolver ignores ErrWikiPageNotFound but wraps any other lookup failure with this error naming the slug and KB. It preserves the underlying cause via %w so callers can errors.Is/As into it. It signals a real backend failure, not a page-missing case.

Source

Thrown at internal/agent/tools/wiki_route_resolver.go:139

	slug = strings.TrimSpace(slug)
	if slug == "" {
		return nil, "", fmt.Errorf("slug is required")
	}
	scopes := NewWikiScopesFromKBIDs(kbIDs)
	preferred := routes.scopesForSlug(slug, scopes)
	ordered := append(append([]WikiScope(nil), preferred...), scopesOutsideKBs(scopes, preferred)...)
	type hit struct {
		page *types.WikiPage
		kbID string
	}
	var hits []hit
	for _, scope := range ordered {
		page, err := service.GetPageBySlug(ctx, scope.KnowledgeBaseID, slug)
		if err != nil {
			if errors.Is(err, repository.ErrWikiPageNotFound) {
				continue
			}
			return nil, "", fmt.Errorf(
				"failed to resolve wiki page %s in knowledge base %s: %w",
				slug, scope.KnowledgeBaseID, err,
			)
		}
		if page == nil {
			continue
		}
		if page.KnowledgeBaseID != "" && page.KnowledgeBaseID != scope.KnowledgeBaseID {
			return nil, "", fmt.Errorf(
				"wiki page %s returned knowledge base %s while resolving allowed scope %s",
				slug, page.KnowledgeBaseID, scope.KnowledgeBaseID,
			)
		}
		kbID := scope.KnowledgeBaseID
		hits = append(hits, hit{page: page, kbID: kbID})
		routes.rememberPage(page, kbID)
	}
	switch len(hits) {

View on GitHub (pinned to 988cbb0330)

Solutions

Inspect the wrapped cause with errors.Is/As to identify the underlying repository error
Check health/connectivity of the wiki page repository (DB or Elasticsearch) for that KB
Verify service credentials/permissions for the failing knowledge base
Retry with backoff if the cause is transient (timeout/cancellation)

Example fix

// caller
page, kbID, err := resolveUniqueWikiPage(ctx, slug, kbIDs, routes)
if err != nil {
    if errors.Is(err, repository.ErrWikiPageNotFound) { /* handle miss */ }
    log.Errorf("wiki resolve failed: %v", err) // prints slug, kb, cause
}

Defensive patterns

Strategy: try-catch

Validate before calling

null

Type guard

null

Try / catch

page, kbID, err := resolveUniqueWikiPage(ctx, slug, kbIDs, routes)
if err != nil {
    var cause error
    if errors.As(err, &cause) && !errors.Is(err, errWikiPageNotFoundInScope) {
        log.Errorf("wiki backend failure: %v", err)
        // retry with backoff or return 5xx-style tool error
    }
}

Prevention

Monitor repository/ES health for wiki KB backends
Keep scopes small to reduce per-scope lookup failure surface
Distinguish ErrWikiPageNotFound from other errors in callers
Use ctx with sensible timeout instead of letting deadlines bubble as opaque errors

When it happens

Trigger: service.GetPageBySlug returns a non-ErrWikiPageNotFound error (repository outage, permission error, context cancellation, index/DB failure) for any of the ordered scopes.

Common situations: Elasticsearch/DB down or timing out; the KB index deleted or corrupted; authz revoking access mid-request; ctx deadline exceeded while iterating several scopes.

Related errors

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