Troubleshoot routing, localization, and multi-sites

Every request resolves to the wrong site (or the default site)

This usually means the request's hostname isn't matching any entry in your site list.

To fix the issue:

• Confirm you're comparing the hostname only (no port, no scheme), and that the comparison is case-insensitive.
• Confirm whether a site's hostname value contains multiple hostnames separated by a delimiter (commonly |); make sure your matching logic splits on it rather than comparing the whole string.
• Confirm whether your local development hostname (such as localhost) is actually registered as a hostname for any site. If not, requests will always fall through to your configured default site, which is expected.
• Confirm your cached site list is up to date. If you added or renamed a site, refresh the cache (or reduce its time-to-live during development).

Requesting a specific language returns null content

If the layout or item query returns null for an item or field when you specify a language, try the following:

• Confirm the language code you're passing matches a language code configured in SitecoreAI exactly, including region (for example, fr-FR, not fr).
• Confirm the content has actually been published in that language (or in a fallback language) to Experience Edge.
• Check whether language fallback is enabled for your environment. Fallback is disabled by default, and there are two separate configuration levels; site-level fallback only affects the Page builder/Content Editor, not GraphQL responses.
• If fallback is enabled but still not returning content, confirm the fallback language version has been published to Experience Edge at least once, so the fallback dependency exists.

Two sites with the same root path don't both resolve correctly

By default, only one site item can point to the same start item. If you're modeling multiple languages as separate site definitions sharing a root path, this requires language-based site resolution to be enabled for your environment, and a full republish afterward. Until that's enabled, only one of the site definitions will resolve as expected.

A redirect rule doesn't seem to apply

To fix the issue:

• Check the order of rules in the redirect map. Rules are evaluated top to bottom, and the first match wins; a broad or catch-all pattern positioned before a more specific one will shadow it.
• If the rule is scoped to a specific locale, confirm you're comparing it against the resolved locale of the request, not the raw path.
• Confirm whether the rule's pattern is a static path or a regular expression, and that your matching logic is applying the correct comparison for each. A static pattern shouldn't be treated as a regex, and vice versa.
• Remember that redirects must be republished (specifically, the site root item) before newly authored or edited rules take effect, since Experience Edge serves a cached copy until then.
• Confirm the redirect was authored as an entry in a redirect map in the Content Editor. SitecoreAI doesn't support standalone redirect items, and redirects aren't configured in the Page builder.
• If you adapted redirect handling from an existing SDK or framework, check whether it gates redirects behind an environment check. For example, the Content SDK's redirects proxy defaults to disabled when NODE_ENV is development, so redirects silently do nothing locally unless you explicitly enable them.

A redirect loops or redirects to the wrong target

To fix the issue:

• If the target contains $1, $2, and so on, confirm the pattern is a regular expression with capture groups; these tokens are only substituted for regex patterns, not static paths.
• If the target contains $siteLang, confirm you're substituting it with the resolved site's language before redirecting.
• If isQueryStringPreserved is set but the redirect target already has its own query string, make sure your merge logic combines both instead of overwriting one with the other.

Performance degrades as the redirect map grows

Because redirects are evaluated on every request, a very large redirect map, or many complex regular expressions, can add noticeable latency. Keep individual redirect maps to roughly 200 entries or fewer, favor static path rules over regular expressions where possible, and make sure you're caching the redirect list per site rather than querying it on every request.

Dictionary keys are missing or return undefined

If a component renderer looks up a site dictionary key and gets nothing back, try the following:

• Confirm a dictionary entry with that exact key exists for your site in the Content Editor's dictionary folder. Keys are case-sensitive.
• Confirm the dictionary item has a version (and a value) in the language you're querying, and that it's been published to Experience Edge.
• Confirm you're paginating through the full result set (pageInfo.hasNext / endCursor); a dictionary with more entries than your page size will otherwise appear to be missing keys past the first page.
• Confirm your dictionary fetch is actually being called and its result is reaching the component, for example by logging the resolved dictionary object before rendering.