What causes "API key is required for Metaso provider" in Tencent/WeKnora?

Set the Metaso API key in the provider parameters (APIKey field) before calling NewMetasoProvider.

API key is required for Metaso provider

Error message

API key is required for Metaso provider

What it means

Returned by ValidateMetasoParameters (and therefore by NewMetasoProvider) when the Metaso provider is constructed without a non-empty APIKey. Metaso's API is authenticated exclusively via a Bearer token, so the provider refuses to initialize rather than failing later at request time with a 401. This is a fail-fast configuration validation error.

Source

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

}

func NewMetasoProvider(params types.WebSearchProviderParameters) (interfaces.WebSearchProvider, error) {
	if err := ValidateMetasoParameters(params); err != nil {
		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) {

View on GitHub (pinned to 988cbb0330)

Solutions

Set the Metaso API key in the provider parameters (APIKey field) before calling NewMetasoProvider.
Verify the environment variable / secret holding the key is actually set and exported where the app runs.
Check that secret injection (CI variables, .env file, secret manager) resolved to a non-empty value.
Trim and check the value yourself before constructing the provider to fail with a clearer app-level message.

Example fix

// before
provider, err := NewMetasoProvider(types.WebSearchProviderParameters{})

// after
apiKey := os.Getenv("METASO_API_KEY")
if strings.TrimSpace(apiKey) == "" {
    return nil, fmt.Errorf("METASO_API_KEY not configured")
}
provider, err := NewMetasoProvider(types.WebSearchProviderParameters{APIKey: apiKey})

Defensive patterns

Strategy: validation

Validate before calling

func requireAPIKey(params types.WebSearchProviderParameters) error {
    if strings.TrimSpace(params.APIKey) == "" {
        return fmt.Errorf("API key is required for Metaso provider")
    }
    return nil
}

// call before NewMetasoProvider:
if err := requireAPIKey(params); err != nil { return err }

Try / catch

provider, err := NewMetasoProvider(params)
if err != nil {
    if strings.Contains(err.Error(), "API key is required") {
        return nil, fmt.Errorf("configuration error: set METASO_API_KEY (%w)", err)
    }
    return nil, err
}

Prevention

Fail fast at application startup by constructing all providers during init.
Use secret-manager checks in CI to assert required secrets are present before deploy.
Document required env vars and validate them with a startup config checklist.
Never build provider parameters from values that can silently resolve to empty strings.

When it happens

Trigger: NewMetasoProvider calls ValidateMetasoParameters; strings.TrimSpace(params.APIKey) == "" — i.e. WebSearchProviderParameters.APIKey unset, empty string, or whitespace only.

Common situations: METASO_API_KEY (or equivalent env var) not set in the environment; config file missing the api_key field; secret injected as empty string because of a failed secret-manager lookup; trailing whitespace-only key after sanitization.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

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