{"record":{"id":"3e81f5514f7cdb8c","repo":"withastro/astro","slug":"incorrectstrategyfori18n","errorCode":"IncorrectStrategyForI18n","errorMessage":"The function `${functionName}` can only be used when the `i18n.routing.strategy` is set to `\"manual\"`.","messagePattern":"The function `(.+?)` can only be used when the `i18n\\.routing\\.strategy` is set to `\"manual\"`\\.","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/virtual-modules/i18n.ts","lineNumber":35,"sourceCode":"import type { MiddlewareHandler } from '../types/public/common.js';\nimport type { AstroConfig, ValidRedirectStatus } from '../types/public/config.js';\nimport type { APIContext } from '../types/public/context.js';\nimport type { ClientDeserializedManifest } from '../types/public/index.js';\n\nconst { trailingSlash, site, i18n, build } = config as ClientDeserializedManifest;\nconst { format } = build;\nconst isBuild = import.meta.env.PROD;\nconst { defaultLocale, locales, domains, fallback, routing } = i18n!;\nconst base = import.meta.env.BASE_URL;\n\nlet strategy = toRoutingStrategy(routing, domains);\nlet fallbackType = toFallbackType(routing);\n\nexport type GetLocaleOptions = I18nInternals.GetLocaleOptions;\n\nconst noop = (method: string) =>\n\tfunction () {\n\t\tthrow new AstroError({\n\t\t\t...IncorrectStrategyForI18n,\n\t\t\tmessage: IncorrectStrategyForI18n.message(method),\n\t\t});\n\t};\n\n/**\n * @param locale A locale\n * @param path An optional path to add after the `locale`.\n * @param options Customise the generated path\n *\n * Returns a _relative_ path with passed locale.\n *\n * ## Errors\n *\n * Throws an error if the locale doesn't exist in the list of locales defined in the configuration.\n *\n * ## Examples\n *","sourceCodeStart":17,"sourceCodeEnd":53,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/src/virtual-modules/i18n.ts#L17-L53","documentation":"Astro i18n exposes several helper functions (`redirectToDefaultLocale`, `notFound`, `requestHasLocale`, `useFallback`, and `middleware`) that are only meaningful when the routing strategy is `\"manual\"`. When the strategy derived from config is anything else (e.g. pathname-prefix, domain-based), these exports are replaced with a `noop` that throws an `AstroError` (code `IncorrectStrategyForI18n`) naming the function. The strategy is computed by `toRoutingStrategy(routing, domains)` from `astro.config` i18n settings.","triggerScenarios":"Importing `redirectToDefaultLocale` from `astro:i18n` and calling it when `i18n.routing` is not `'manual'`. Importing `middleware` from `astro:i18n` and registering it in `astro.config` middleware while routing is automatic. Calling `notFound()` or `requestHasLocale(ctx)` outside manual routing.","commonSituations":"Following a tutorial or copying middleware code that assumes manual routing while your config uses the default automatic locale-prefix strategy. Upgrading Astro where the default strategy changed. Setting `i18n.routing: 'manual'` is required to opt into these helpers — without it the virtual module assigns the throwing noop.","solutions":["Set `i18n.routing: 'manual'` in astro.config.mjs to enable these helper functions.","If you do not need manual control, stop importing/calling the throwing functions (redirectToDefaultLocale, notFound, requestHasLocale, middleware) and rely on automatic routing instead.","Confirm `domains` config does not implicitly override the strategy if you intended manual."],"exampleFix":"// before — astro.config.mjs\nexport default defineConfig({ i18n: { defaultLocale: 'en', locales: ['en','es'] } });\n// code: import { middleware } from 'astro:i18n';\n\n// after\nexport default defineConfig({ i18n: { defaultLocale: 'en', locales: ['en','es'], routing: 'manual' } });","handlingStrategy":"validation","validationCode":"import { getRelativeLocaleUrl } from 'astro:i18n';\n// Before relying on manual-only helpers, check your config:\n// astro.config.mjs must have i18n.routing === 'manual'.\n// At runtime you cannot read the strategy directly; guard your calls:\nfunction requireManualRouting(config) {\n  if (config.i18n?.routing !== 'manual') {\n    throw new Error('Set i18n.routing to \"manual\" to use i18n helpers');\n  }\n}","typeGuard":null,"tryCatchPattern":"import { redirectToDefaultLocale } from 'astro:i18n';\ntry {\n  redirectToDefaultLocale(context);\n} catch (e) {\n  if (e.errorCode === 'IncorrectStrategyForI18n') {\n    // Fallback: do manual redirect or skip\n  } else throw e;\n}","preventionTips":["Set `i18n.routing: 'manual'` before importing any manual-only helper.","Keep i18n helper usage in one module so the routing assumption is centralized.","Document which helpers require manual routing in your project's i18n README."],"tags":["i18n","routing","configuration"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}