{"record":{"id":"6442d6146da1bf9a","repo":"withastro/astro","slug":"the-integration-name-integration-is-trying-to","errorCode":null,"errorMessage":"The \"${integration.name}\" integration is trying to add the \"${name}\" client directive, but it already exists.","messagePattern":"The \"(.+?)\" integration is trying to add the \"(.+?)\" client directive, but it already exists\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/astro/src/integrations/hooks.ts","lineNumber":275,"sourceCode":"\t\t\t\t\tinjectRoute: (injectRoute) => {\n\t\t\t\t\t\tif (injectRoute.entrypoint == null && 'entryPoint' in injectRoute) {\n\t\t\t\t\t\t\tlogger.warn(\n\t\t\t\t\t\t\t\tnull,\n\t\t\t\t\t\t\t\t`The injected route \"${injectRoute.pattern}\" by ${integration.name} specifies the entry point with the \"entryPoint\" property. This property is deprecated, please use \"entrypoint\" instead.`,\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\tinjectRoute.entrypoint = injectRoute.entryPoint as string;\n\t\t\t\t\t\t}\n\t\t\t\t\t\tupdatedSettings.injectedRoutes.push({ ...injectRoute, origin: 'external' });\n\t\t\t\t\t},\n\t\t\t\t\taddWatchFile: (path) => {\n\t\t\t\t\t\tupdatedSettings.watchFiles.push(path instanceof URL ? fileURLToPath(path) : path);\n\t\t\t\t\t},\n\t\t\t\t\taddDevToolbarApp: (entrypoint) => {\n\t\t\t\t\t\tupdatedSettings.devToolbarApps.push(entrypoint);\n\t\t\t\t\t},\n\t\t\t\t\taddClientDirective: ({ name, entrypoint }) => {\n\t\t\t\t\t\tif (updatedSettings.clientDirectives.has(name) || addedClientDirectives.has(name)) {\n\t\t\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t\t\t`The \"${integration.name}\" integration is trying to add the \"${name}\" client directive, but it already exists.`,\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t}\n\t\t\t\t\t\t// TODO: this should be performed after astro:config:done\n\t\t\t\t\t\taddedClientDirectives.set(\n\t\t\t\t\t\t\tname,\n\t\t\t\t\t\t\tbuildClientDirectiveEntrypoint(name, entrypoint, settings.config.root),\n\t\t\t\t\t\t);\n\t\t\t\t\t},\n\t\t\t\t\taddMiddleware: ({ order, entrypoint }) => {\n\t\t\t\t\t\tif (typeof updatedSettings.middlewares[order] === 'undefined') {\n\t\t\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t\t\t`The \"${integration.name}\" integration is trying to add middleware but did not specify an order.`,\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t}\n\t\t\t\t\t\tlogger.debug(\n\t\t\t\t\t\t\t'middleware',\n\t\t\t\t\t\t\t`The integration ${integration.name} has added middleware that runs ${","sourceCodeStart":257,"sourceCodeEnd":293,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/src/integrations/hooks.ts#L257-L293","documentation":"`addClientDirective` rejects a directive whose `name` is already present in either `settings.clientDirectives` (built-in or previously built) or `addedClientDirectives` (already added this config-setup pass). Client directive names must be globally unique.","triggerScenarios":"Two integrations both call `addClientDirective({ name: 'foo', ... })`, or an integration registers a name that collides with Astro's built-in directives (`client:load`, `client:idle`, `client:visible`, `client:media`, `client:only`).","commonSituations":"Installing two integrations that define the same custom client directive; re-registering a directive on config restart; naming a custom directive identically to a built-in.","solutions":["Rename your custom directive to a unique name not used by built-ins or other loaded integrations.","Remove one of the conflicting integrations, or check whether the directive is already provided.","Guard registration by checking existing directive names before calling `addClientDirective`."],"exampleFix":"// before — two integrations both register 'foo'\naddClientDirective({ name: 'foo', entrypoint: '...' })\n\n// after — namespace the directive name per integration\naddClientDirective({ name: '@mine/foo', entrypoint: '...' })","handlingStrategy":"validation","validationCode":"const BUILTIN = new Set(['load','idle','visible','media','only']);\nfunction isDirectiveNameTaken(name, settings, added) {\n  return settings.clientDirectives.has(name) || added.has(name) || BUILTIN.has(name);\n}","typeGuard":"function isUniqueDirectiveName(name, settings, added) {\n  return !settings.clientDirectives.has(name) && !added.has(name);\n}","tryCatchPattern":"null","preventionTips":["Namespace custom directive names per integration.","Avoid the built-in client:* names.","Check existing directives before registering."],"tags":["integrations","client-directives","config"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}