{"record":{"id":"83edcd5912ddc56e","repo":"withastro/astro","slug":"cachequeryconfigconflict","errorCode":"CacheQueryConfigConflict","errorMessage":"`query.include` and `query.exclude` cannot be used together. Use `include` to allowlist specific parameters, or `exclude` to blocklist them.","messagePattern":"`query\\.include` and `query\\.exclude` cannot be used together\\. Use `include` to allowlist specific parameters, or `exclude` to blocklist them\\.","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/core/cache/memory-provider.ts","lineNumber":153,"sourceCode":"\t'oly_enc_id',\n\t'rb_clickid',\n\t's_cid',\n\t'vero_id',\n\t'wickedid',\n\t'yclid',\n\t'__s',\n\t'ref',\n];\n\ninterface NormalizedQueryConfig {\n\tsort: boolean;\n\tinclude: string[] | null;\n\texcludeMatcher: picomatch.Matcher | null;\n}\n\nfunction normalizeQueryConfig(query: MemoryCacheQueryOptions | undefined): NormalizedQueryConfig {\n\tif (query?.include && query?.exclude) {\n\t\tthrow new AstroError(CacheQueryConfigConflict);\n\t}\n\n\tconst sort = query?.sort !== false;\n\tconst include = query?.include ?? null;\n\n\t// When `include` is set, exclude is irrelevant — only the allowlisted params matter.\n\tconst excludePatterns = include ? [] : (query?.exclude ?? DEFAULT_EXCLUDED_PARAMS);\n\tconst excludeMatcher =\n\t\texcludePatterns.length > 0 ? picomatch(excludePatterns, { nocase: true }) : null;\n\treturn { sort, include, excludeMatcher };\n}\n\n/**\n * Build the query string portion of a cache key, applying sorting and filtering.\n */\nfunction buildQueryString(url: URL, config: NormalizedQueryConfig): string {\n\tconst params = new URLSearchParams(url.searchParams);\n","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/src/core/cache/memory-provider.ts#L135-L171","documentation":"The memory cache's query-key normalization refuses to accept both an `include` allowlist and an `exclude` blocklist at the same time, because their semantics are contradictory (include restricts to a set; exclude removes from all). Allowing both would leave the actual cache-key behavior ambiguous. Astro throws this during config normalization so the intent is unambiguous at startup.","triggerScenarios":"Calling `memoryCache({ query: { include: ['page'], exclude: ['utm_*'] } })` — passing both `query.include` and `query.exclude` as non-empty values to the `memoryCache` provider factory. The check fires in `normalizeQueryConfig` the moment `query?.include && query?.exclude` are both truthy.","commonSituations":"Copying an `exclude` snippet from docs and then adding an `include` list; migrating from a blocklist strategy to an allowlist without removing the old `exclude` key; merging two cache config objects where one supplies `include` and the other supplies `exclude`.","solutions":["Pick one strategy: keep `query.include` and delete `query.exclude` (allowlist), or keep `query.exclude` and delete `query.include` (blocklist).","If you need allowlist semantics with a few exclusions, note that `include` already ignores everything not listed, so exclusions are redundant — use only `include`.","If you want default tracking-param exclusion plus your own blocklist, omit `include` and pass only `exclude` (it replaces the defaults)."],"exampleFix":"// before\nimport { memoryCache } from 'astro/cache/memory';\nmemoryCache({ query: { include: ['page', 'q'], exclude: ['utm_*'] } });\n\n// after\nimport { memoryCache } from 'astro/cache/memory';\nmemoryCache({ query: { include: ['page', 'q'] } });","handlingStrategy":"validation","validationCode":"function assertCacheQuery(q) {\n  if (q && q.include && q.exclude) {\n    throw new Error('Pass only one of query.include or query.exclude to memoryCache().');\n  }\n}","typeGuard":"function isSingleStrategyQuery(q) {\n  return !(q && q.include && q.exclude);\n}","tryCatchPattern":null,"preventionTips":["Validate cache query config once at module load before passing to memoryCache().","Document in your config module which strategy (allowlist vs blocklist) the project uses.","Avoid merging arbitrary user/env config into the cache query object."],"tags":["cache","configuration","config-conflict"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}