AdguardTeam/AdGuardHome · error

creating safesearch for client %q: %w

Error message

creating safesearch for client %q: %w

What it means

Creating the safe-search configuration for a client failed while converting JSON to a client object. The wrapped error comes from the safe-search engine when the client's SafeSearchConf is invalid or the cache settings are unusable.

Source

Thrown at internal/home/clientshttp.go:228

	c.ParentalEnabled = cj.ParentalEnabled
	c.SafeBrowsingEnabled = cj.SafeBrowsingEnabled
	c.UseOwnBlockedServices = !cj.UseGlobalBlockedServices

	if c.SafeSearchConf.Enabled {
		logger := clients.baseLogger.With(
			slogutil.KeyPrefix, safesearch.LogPrefix,
			safesearch.LogKeyClient, c.Name,
		)
		var ss *safesearch.Default
		ss, err = safesearch.NewDefault(ctx, &safesearch.DefaultConfig{
			Logger:         logger,
			ServicesConfig: c.SafeSearchConf,
			ClientName:     c.Name,
			CacheSize:      clients.safeSearchCacheSize,
			CacheTTL:       clients.safeSearchCacheTTL,
		})
		if err != nil {
			return nil, fmt.Errorf("creating safesearch for client %q: %w", c.Name, err)
		}

		c.SafeSearch = ss
	}

	return c, nil
}

// copySafeSearch returns safe search config created from provided parameters.
func copySafeSearch(
	jsonConf *filtering.SafeSearchConfig,
	enabled bool,
) (conf filtering.SafeSearchConfig) {
	if jsonConf != nil {
		return *jsonConf
	}

	// TODO(d.kolyshev): Remove after cleaning the deprecated

View on GitHub (pinned to b41aefbe51)

Solutions

1. Check the wrapped error for the specific safe-search setting at fault
2. Simplify the request: omit safe-search fields, then re-add them one at a time
3. Verify global safe-search cache size/TTL configuration is sane
4. Upgrade both client tooling and server to matching versions

// Omit or null safe_search fields when unsure
if !validatedSafeSearch(payload.SafeSearchConf) { payload.SafeSearchConf = nil }

// Degrade gracefully: resend without safe-search settings
if isSafeSearchErr(err) { payload.SafeSearchConf = nil; retry() }

When it happens

Trigger: handleAddClient/handleUpdateClient (or internal consistency assertions) with a client whose SafeSearchConf fails to build into a safe-search set, e.g. invalid engine options or bad cache size/TTL values.

Common situations: API payloads with malformed safe-search settings, inconsistent global safe-search cache configuration, or version mismatches where the config schema changed.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

• invalid blocked services: %w
• decoding json: %w
• json time is nil
• interface %s has no ipv6 addresses
• invalid ip version %d

AI-assisted analysis of AdguardTeam/AdGuardHome@b41aefbe51 (2026-08-27). Data as JSON: /api/errors/9c13320c26d6d875. Report an issue: GitHub.