Tencent/WeKnora · error

invalid Metaso search scope

Error message

invalid Metaso search scope: %s

What it means

Returned by ValidateMetasoParameters when the configured Metaso search scope (derived from ExtraConfig["scope"]) is not one of the entries in validMetasoScopes. Metaso only accepts a fixed set of scopes (e.g. webpage/document/image etc.), and an unknown value would cause API-side rejections, so the provider validates it up front. The invalid value is included in the message.

Solutions

1. Check the error message for the offending scope value and compare against the provider's validMetasoScopes list (see metaso.go).
2. Set ExtraConfig["scope"] to one of the documented valid values (or omit it entirely to use the default).
3. Fix casing/typos — scopes are matched exactly, not case-insensitively.
4. Add a whitelist check in your own config loading to reject bad scopes before constructing the provider.

Example fix

// before
cfg := types.WebSearchProviderParameters{APIKey: key, ExtraConfig: map[string]string{"scope": "web"}}

// after: use a documented valid scope
cfg := types.WebSearchProviderParameters{APIKey: key, ExtraConfig: map[string]string{"scope": "webpage"}}

var validMetasoScopes = map[string]bool{"webpage": true, "document": true, "image": true}

scope := strings.TrimSpace(cfg.ExtraConfig["scope"])
if scope != "" && !validMetasoScopes[scope] {
    return fmt.Errorf("invalid Metaso scope %q; valid: webpage, document, image", scope)
}

if err := ValidateMetasoParameters(params); err != nil {
    if strings.Contains(err.Error(), "invalid Metaso search scope") {
        return nil, fmt.Errorf("check your scope setting: %w", err)
    }
    return err
}

When it happens

Trigger: NewMetasoProvider -> ValidateMetasoParameters where metasoScope(params.ExtraConfig) returns a value not in validMetasoScopes — e.g. ExtraConfig{scope: "web"} when the provider expects "webpage", a typo, or wrong casing.

Common situations: Copy-pasted scope name from another provider's config; typo like "webpages" vs "webpage"; user-facing setting passing free-form text into scope; empty-but-set value that skips the default and is not whitelisted.

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

• API key is required for Metaso provider
• API key is required for Ollama provider
• API key is required for Baidu provider
• API key is required for Exa provider
• API key is required for Exa provider

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

Appendix: source

Thrown at internal/infrastructure/web_search/metaso.go:60

		return nil, err
	}
	client, err := NewSearchHTTPClient(defaultMetasoTimeout, params.ProxyURL)
	if err != nil {
		return nil, err
	}
	return &MetasoProvider{
		client: client, baseURL: defaultMetasoSearchURL,
		apiKey: strings.TrimSpace(params.APIKey), scope: metasoScope(params.ExtraConfig),
	}, nil
}

func ValidateMetasoParameters(params types.WebSearchProviderParameters) error {
	if strings.TrimSpace(params.APIKey) == "" {
		return fmt.Errorf("API key is required for Metaso provider")
	}
	scope := metasoScope(params.ExtraConfig)
	if _, ok := validMetasoScopes[scope]; !ok {
		return fmt.Errorf("invalid Metaso search scope: %s", scope)
	}
	return nil
}

func metasoScope(extraConfig map[string]string) string {
	if scope := strings.TrimSpace(extraConfig["scope"]); scope != "" {
		return scope
	}
	return defaultMetasoScope
}

func (p *MetasoProvider) Name() string { return "metaso" }

func (p *MetasoProvider) Search(ctx context.Context, query string, maxResults int, includeDate bool) ([]*types.WebSearchResult, error) {
	query = strings.TrimSpace(query)
	if query == "" {
		return nil, fmt.Errorf("query is empty")
	}

View on GitHub (pinned to 988cbb0330)