https://www.eventcatalog.dev/assets/js/ae69f9fb.5f401112.js

1"use strict";(globalThis.webpackChunkeventcatalog_docs=globalThis.webpackChunkeventcatalog_docs||[]).push([[4345],{31735:(e,r,n)=>{n.d(r,{A:()=>i});n(30758);var s=n(86070);const i=({url:e})=>(0,s.jsx)("div",{style:{marginBottom:"1em"},className:"added-in",children:(0,s.jsx)("code",{children:(0,s.jsx)("a",{style:{color:"white"},href:"https://www.eventcatalog.dev/pricing",children:"EventCatalog Enterprise Feature"})})})},48193:(e,r,n)=>{n.d(r,{R:()=>d,x:()=>c});var s=n(30758);const i={},t=s.createContext(i);function d(e){const r=s.useContext(t);return s.useMemo(function(){return"function"==typeof e?e(r):{...r,...e}},[r,e])}function c(e){let r;return r=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:d(e.components),s.createElement(t.Provider,{value:r},e.children)}},89645:(e,r,n)=>{n.r(r),n.d(r,{assets:()=>l,contentTitle:()=>o,default:()=>x,frontMatter:()=>c,metadata:()=>s,toc:()=>a});const s=JSON.parse('{"id":"federation/reference/diagnostic-rules","title":"Federation diagnostic rule reference","description":"Reference for every Federation rule, default level, trigger, output attributes, and resolution.","source":"@site/docs/federation/reference/diagnostic-rules.md","sourceDirName":"federation/reference","slug":"/federation/reference/diagnostic-rules","permalink":"/docs/federation/reference/diagnostic-rules","draft":false,"unlisted":false,"editUrl":"https://github.com/event-catalog/docs/tree/main/docs/federation/reference/diagnostic-rules.md","tags":[],"version":"current","sidebarPosition":3,"frontMatter":{"sidebar_position":3,"sidebar_label":"Diagnostic rules","title":"Federation diagnostic rule reference","description":"Reference for every Federation rule, default level, trigger, output attributes, and resolution."},"sidebar":"federationSidebar","previous":{"title":"CLI","permalink":"/docs/federation/reference/cli"},"next":{"title":"Supported content","permalink":"/docs/federation/reference/supported-content"}}');var i=n(86070),t=n(48193),d=n(31735);const c={sidebar_position:3,sidebar_label:"Diagnostic rules",title:"Federation diagnostic rule reference",description:"Reference for every Federation rule, default level, trigger, output attributes, and resolution."},o=void 0,l={},a=[{value:"<code>federation/duplicate-source</code>",id:"federationduplicate-source",level:2},{value:"<code>federation/type-collision</code>",id:"federationtype-collision",level:2},{value:"<code>federation/pointer-type-mismatch</code>",id:"federationpointer-type-mismatch",level:2},{value:"<code>federation/facet-disagreement</code>",id:"federationfacet-disagreement",level:2},{value:"<code>federation/asset-collision</code>",id:"federationasset-collision",level:2},{value:"<code>federation/missing-resource</code>",id:"federationmissing-resource",level:2},{value:"<code>federation/unresolved-version</code>",id:"federationunresolved-version",level:2},{value:"Configure levels",id:"configure-levels",level:2},{value:"Operational errors without rule IDs",id:"operational-errors-without-rule-ids",level:2}];function h(e){const r={a:"a",code:"code",h2:"h2",li:"li",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,t.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(d.A,{}),"\n",(0,i.jsxs)(r.p,{children:["Federation diagnostics use stable rule IDs. Configure each rule as ",(0,i.jsx)(r.code,{children:"off"}),", ",(0,i.jsx)(r.code,{children:"warn"}),", or ",(0,i.jsx)(r.code,{children:"error"})," under ",(0,i.jsx)(r.code,{children:"federation.rules"}),"."]}),"\n",(0,i.jsxs)(r.table,{children:[(0,i.jsx)(r.thead,{children:(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.th,{children:"Rule"}),(0,i.jsx)(r.th,{children:"Default"}),(0,i.jsx)(r.th,{children:"Summary"})]})}),(0,i.jsxs)(r.tbody,{children:[(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"federation/duplicate-source"})}),(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"error"})}),(0,i.jsx)(r.td,{children:"A resource has multiple owning catalogs"})]}),(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"federation/type-collision"})}),(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"error"})}),(0,i.jsx)(r.td,{children:"One resource ID is documented with conflicting types"})]}),(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"federation/pointer-type-mismatch"})}),(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"error"})}),(0,i.jsx)(r.td,{children:"A relationship expects the wrong target type"})]}),(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"federation/facet-disagreement"})}),(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"error"})}),(0,i.jsx)(r.td,{children:"Catalogs provide contradictory facets for a resource"})]}),(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"federation/asset-collision"})}),(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"warn"})}),(0,i.jsx)(r.td,{children:"Remote sources publish different files at one asset path"})]}),(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"federation/missing-resource"})}),(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"warn"})}),(0,i.jsx)(r.td,{children:"A relationship points to an ID that is not present"})]}),(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"federation/unresolved-version"})}),(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"warn"})}),(0,i.jsx)(r.td,{children:"The target ID exists, but its requested version does not"})]})]})]}),"\n",(0,i.jsx)(r.h2,{id:"federationduplicate-source",children:(0,i.jsx)(r.code,{children:"federation/duplicate-source"})}),"\n",(0,i.jsxs)(r.p,{children:[(0,i.jsx)(r.strong,{children:"Message:"})," ",(0,i.jsx)(r.code,{children:"Resource has multiple owners"})]}),"\n",(0,i.jsx)(r.p,{children:"Triggered when the same resource ID and type are owned by more than one catalog. All versions of one resource ID must have the same owner."}),"\n",(0,i.jsx)(r.p,{children:"Attributes:"}),"\n",(0,i.jsxs)(r.table,{children:[(0,i.jsx)(r.thead,{children:(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.th,{children:"Attribute"}),(0,i.jsx)(r.th,{children:"Meaning"})]})}),(0,i.jsxs)(r.tbody,{children:[(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"resource"})}),(0,i.jsx)(r.td,{children:"Conflicting resource ID"})]}),(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"catalogs"})}),(0,i.jsx)(r.td,{children:"Catalogs claiming ownership"})]}),(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"resolution"})}),(0,i.jsx)(r.td,{children:"Suggested ownership action"})]})]})]}),"\n",(0,i.jsx)(r.p,{children:"Resolution: choose one owning catalog. Remove c

1opied or placeholder resource definitions from consumers."}),"\n",(0,i.jsx)(r.h2,{id:"federationtype-collision",children:(0,i.jsx)(r.code,{children:"federation/type-collision"})}),"\n",(0,i.jsxs)(r.p,{children:[(0,i.jsx)(r.strong,{children:"Message:"})," ",(0,i.jsx)(r.code,{children:"Resource ID has conflicting types"})]}),"\n",(0,i.jsx)(r.p,{children:"Triggered when the same resource ID is documented as different EventCatalog resource types, such as an event in one catalog and a command in another."}),"\n",(0,i.jsx)(r.p,{children:"Attributes:"}),"\n",(0,i.jsxs)(r.table,{children:[(0,i.jsx)(r.thead,{children:(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.th,{children:"Attribute"}),(0,i.jsx)(r.th,{children:"Meaning"})]})}),(0,i.jsxs)(r.tbody,{children:[(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"resource"})}),(0,i.jsx)(r.td,{children:"Conflicting resource ID"})]}),(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"<catalog ID>"})}),(0,i.jsx)(r.td,{children:"Type documented by that catalog"})]})]})]}),"\n",(0,i.jsx)(r.p,{children:"Resolution: correct the resource type or use distinct IDs for different resources."}),"\n",(0,i.jsx)(r.h2,{id:"federationpointer-type-mismatch",children:(0,i.jsx)(r.code,{children:"federation/pointer-type-mismatch"})}),"\n",(0,i.jsxs)(r.p,{children:[(0,i.jsx)(r.strong,{children:"Message:"})," ",(0,i.jsx)(r.code,{children:"Reference type does not match resource"})]}),"\n",(0,i.jsx)(r.p,{children:"Triggered when a relationship pointer expects one target type but the resolved resource has another type."}),"\n",(0,i.jsx)(r.p,{children:"Attributes:"}),"\n",(0,i.jsxs)(r.table,{children:[(0,i.jsx)(r.thead,{children:(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.th,{children:"Attribute"}),(0,i.jsx)(r.th,{children:"Meaning"})]})}),(0,i.jsxs)(r.tbody,{children:[(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"resource"})}),(0,i.jsx)(r.td,{children:"Referenced resource ID"})]}),(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"expected type"})}),(0,i.jsx)(r.td,{children:"Type required by the relationship"})]}),(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"actual type"})}),(0,i.jsx)(r.td,{children:"Type documented by the owner"})]}),(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"catalogs"})}),(0,i.jsx)(r.td,{children:"Catalogs involved in the mismatch"})]})]})]}),"\n",(0,i.jsx)(r.p,{children:"Resolution: correct the pointer or point it to the intended resource ID."}),"\n",(0,i.jsx)(r.h2,{id:"federationfacet-disagreement",children:(0,i.jsx)(r.code,{children:"federation/facet-disagreement"})}),"\n",(0,i.jsxs)(r.p,{children:[(0,i.jsx)(r.strong,{children:"Message:"})," ",(0,i.jsx)(r.code,{children:"Catalogs disagree about this resource"})]}),"\n",(0,i.jsx)(r.p,{children:"Represents contradictory contributed facets for a resource, such as incompatible content supplied for the same facet by several catalogs."}),"\n",(0,i.jsx)(r.p,{children:"Attributes:"}),"\n",(0,i.jsxs)(r.table,{children:[(0,i.jsx)(r.thead,{children:(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.th,{children:"Attribute"}),(0,i.jsx)(r.th,{children:"Meaning"})]})}),(0,i.jsxs)(r.tbody,{children:[(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"resource"})}),(0,i.jsx)(r.td,{children:"Resource ID with contradictory facets"})]}),(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"detail"})}),(0,i.jsx)(r.td,{children:"Available disagreement detail"})]}),(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"catalogs"})}),(0,i.jsx)(r.td,{children:"Catalogs contributing the conflicting values"})]})]})]}),"\n",(0,i.jsx)(r.p,{children:"Resolution: decide which source is authoritative and align or remove the conflicting contribution."}),"\n",(0,i.jsx)(r.h2,{id:"federationasset-collision",children:(0,i.jsx)(r.code,{children:"federation/asset-collision"})}),"\n",(0,i.jsxs)(r.p,{children:[(0,i.jsx)(r.strong,{children:"Message:"})," ",(0,i.jsx)(r.code,{children:"Asset collision"})]}),"\n",(0,i.jsxs)(r.p,{children:["Triggered when remote sources publish different c

1ontent to the same ",(0,i.jsx)(r.code,{children:"public/"})," or ",(0,i.jsx)(r.code,{children:"components/"})," path."]}),"\n",(0,i.jsx)(r.p,{children:"Attributes:"}),"\n",(0,i.jsxs)(r.table,{children:[(0,i.jsx)(r.thead,{children:(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.th,{children:"Attribute"}),(0,i.jsx)(r.th,{children:"Meaning"})]})}),(0,i.jsxs)(r.tbody,{children:[(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"asset"})}),(0,i.jsx)(r.td,{children:"Conflicting catalog-relative asset path"})]}),(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"sources"})}),(0,i.jsx)(r.td,{children:"Sources publishing the path"})]}),(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"winner"})}),(0,i.jsx)(r.td,{children:"Source selected by Federation"})]}),(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"resolution"})}),(0,i.jsxs)(r.td,{children:["Selection rule, currently ",(0,i.jsx)(r.code,{children:"last configured source wins"})]})]})]})]}),"\n",(0,i.jsx)(r.p,{children:"Resolution: namespace the paths, make the files identical, or deliberately order the sources and keep the warning visible."}),"\n",(0,i.jsx)(r.p,{children:"An existing public asset owned by the central catalog is preserved."}),"\n",(0,i.jsx)(r.h2,{id:"federationmissing-resource",children:(0,i.jsx)(r.code,{children:"federation/missing-resource"})}),"\n",(0,i.jsxs)(r.p,{children:[(0,i.jsx)(r.strong,{children:"Message:"})," ",(0,i.jsx)(r.code,{children:"Referenced EventCatalog resource does not exist"})]}),"\n",(0,i.jsx)(r.p,{children:"Triggered when a relationship points to a resource ID that is not documented by any participating remote or central catalog."}),"\n",(0,i.jsx)(r.p,{children:"Attributes:"}),"\n",(0,i.jsxs)(r.table,{children:[(0,i.jsx)(r.thead,{children:(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.th,{children:"Attribute"}),(0,i.jsx)(r.th,{children:"Meaning"})]})}),(0,i.jsxs)(r.tbody,{children:[(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"source catalog"})}),(0,i.jsx)(r.td,{children:"Catalog containing the relationship pointer"})]}),(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"referenced by"})}),(0,i.jsx)(r.td,{children:"Resource containing the pointer"})]}),(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"missing resource"})}),(0,i.jsx)(r.td,{children:"Missing ID and requested version, when present"})]})]})]}),"\n",(0,i.jsx)(r.p,{children:"Resolution: add the owning catalog, document the resource in its owner, or correct the pointer ID."}),"\n",(0,i.jsx)(r.h2,{id:"federationunresolved-version",children:(0,i.jsx)(r.code,{children:"federation/unresolved-version"})}),"\n",(0,i.jsxs)(r.p,{children:[(0,i.jsx)(r.strong,{children:"Message:"})," ",(0,i.jsx)(r.code,{children:"Referenced EventCatalog resource version does not exist"})]}),"\n",(0,i.jsx)(r.p,{children:"Triggered when the resource ID exists, but no available version satisfies the pointer."}),"\n",(0,i.jsx)(r.p,{children:"Attributes:"}),"\n",(0,i.jsxs)(r.table,{children:[(0,i.jsx)(r.thead,{children:(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.th,{children:"Attribute"}),(0,i.jsx)(r.th,{children:"Meaning"})]})}),(0,i.jsxs)(r.tbody,{children:[(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"source catalog"})}),(0,i.jsx)(r.td,{children:"Catalog containing the relationship pointer"})]}),(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"referenced by"})}),(0,i.jsx)(r.td,{children:"Versioned resource containing the pointer"})]}),(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"resource"})}),(0,i.jsx)(r.td,{children:"Target resource ID"})]}),(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"requested version"})}),(0,i.jsx)(r.td,{children:"Exact version, range, or authored pointer value"})]}),(0,i.jsxs)(r.tr,{children:[(0,i.jsx)(r.td,{children:(0,i.jsx)(r.code,{children:"available versions"})}),(0,i.jsx)(r.td,{children:"Versions published by the owner"})]})]})]}),"\n",(0,i.jsx)(r.p,{children:"Resolution: change the pointer to an available version or publish a matching version in the owning catalog."}),"\n",(0,i.jsx)(r.h2,{id:"configure-levels",children:"Configure levels"}),"\n",(0,i.jsx)(r.pre,{children:(0,i.jsx)(r.code,{className:"language-js",metastring:'title="eventcatalog.config.js"',children:"export default {\n  federation: {\n    rules: {\n      'federation/missing-resource': 'error',\n      'federation/unresolved-version': 'error',\n      'federation/asset-collision': 'off',\n    },\n    sources: [/* ... */],\n  },\n};\n"})}),"\n",(0,i.jsxs)(r.p,{children:["Changing structural rules from ",(0,i.jsx)(r.code,{children:"error"})," can allow ambiguous ownership or types into the generated view. See ",(0,i.jsx)(r.a,{href:"/docs/federation/how-to/configure-validation-rules",children:"Configure validation rules"}),"."]}),"\n",(0,i.jsx)(r.h2,{id:"operational-errors-without-rule-ids",children:"Operational errors without rule IDs"}),"\n",(0,i.jsxs)(r.p,{children:["Some failures stop Federation directly and do not have configurable ",(0,i.jsx)(r.code,{children:"federation/*"})," rule IDs. These include:"]}),"\n",(0,i.jsxs)(r.ul,{children:["\n",(0,i.jsx)(r.li,{children:"Missing or invalid license access"}),"\n",(0,i.jsx)(r.li,{children:"Duplicate configured source IDs"}),"\n",(0,i.jsx)(r.li,{children:"Unsupported source locators"}),"\n",(0,i.jsx)(r.li,{children:"GitHub authentication or network failures"}),"\n",(0,i.jsx)(r.li,{children:"Missing filesystem source directories"}),"\n",(0,i.jsx)(r.li,{children:"Unsafe source, catalog, or artifact paths"}),"\n",(0,i.jsx)(r.li,{children:"Invalid published indexes"}),"\n",(0,i.jsx)(r.li,{children:"Content hash mismatches"}),"\n",(0,i.jsx)(r.li,{children:"Unreadable lockfiles"}),"\n",(0,i.jsx)(r.li,{children:"Filesystem write or rollback failures"}),"\n"]}),"\n",(0,i.jsxs)(r.p,{children:["See ",(0,i.jsx)(r.a,{href:"/docs/federation/reference/troubleshooting",children:"Troubleshooting Federation"}),"."]})]})}function x(e={}){const{wrapper:r}={...(0,t.R)(),...e.components};return r?(0,i.jsx)(r,{...e,children:(0,i.jsx)(h,{...e})}):h(e)}}}]);