{"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":156,"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":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/withastro/astro/blob/e294953aa8aadd98d5be92e60a03037b05dbdfd4/packages/astro/src/core/cache/memory-provider.ts#L138-L174","documentation":"Cache query options control which URL search parameters participate in the cache key: include is an allowlist, exclude a blocklist. normalizeQueryConfig throws CacheQueryConfigConflict when both are set, because combining them would make the effective key ambiguous.","triggerScenarios":"Passing { query: { include: ['page'], exclude: ['utm_*'] } } in a cache hint — for example Astro.cache.set(), route cache options, or a middleware setting cacheHint on the response.","commonSituations":"Merging copied config fragments from docs and examples; iterating on cache-key tuning and forgetting to remove one side; converting an exclude list to an allowlist without deleting the old key.","solutions":["Keep exactly one of query.include or query.exclude.","Prefer include for an explicit allowlist — every parameter not listed is ignored automatically.","Delete the exclude patterns; with include set they are redundant by design."],"exampleFix":"// before\nAstro.cache.set({\n  query: { include: ['page'], exclude: ['utm_source', 'ref'] },\n});\n\n// after\nAstro.cache.set({\n  query: { include: ['page'] },\n});","handlingStrategy":"validation","validationCode":"// Validate cache hints before applying them\nfunction assertCacheQuery(query: { include?: string[]; exclude?: string[] } = {}) {\n  if (query.include && query.exclude) {\n    throw new Error('cache query: use only one of include or exclude');\n  }\n}\nassertCacheQuery(hint.query);\nAstro.cache.set(hint);","typeGuard":"const isValidCacheQuery = (q?: { include?: string[]; exclude?: string[] }): boolean =>\n  !(q?.include && q?.exclude);","tryCatchPattern":null,"preventionTips":["Pick one strategy per route: an allowlist (include) or a blocklist (exclude), never both.","Remember include already excludes everything unlisted, making exclude redundant.","Centralize cache hints in one helper so conflicting options are caught in one place."],"tags":["cache","configuration","query-params","cache-key"],"backgroundTag":"mutually-exclusive-options","analyzedSha":"e294953aa8aadd98d5be92e60a03037b05dbdfd4","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}