--- title: "ard.json and ai-catalog.json Errors: Fix Your Agent Catalog" description: "Fix ai-catalog.json errors: what SeenLens and Lighthouse check, the ARD entry fields, the move to ard.json, a minimal valid file, and when to return 404." url: https://seenlens.com/fixes/ai-catalog-json-errors last_updated: 2026-11-06 --- # ard.json and ai-catalog.json errors: how to fix your agent catalog An agent catalog is a JSON file that lists agent resources, such as MCP servers and A2A agents, so agents can discover them. It lives at /.well-known/ard.json, or at the older ai-catalog.json. SeenLens reports an error when the file exists but is wrong, or when a catch-all page answers the path with HTML. If you have nothing to list, return a real 404 and the check does not apply. By SeenLens. Last updated: 2026-11-06 ## What does the agent catalog check test? Since rules 0.3.2 (2026-11-06), SeenLens first requests `/.well-known/ard.json`, the location Lighthouse 13.6 and ARD v0.91 use. If that file answers 200, SeenLens checks it with the rules below and ignores the `specVersion` value, as Lighthouse does. If it does not exist, SeenLens falls back to the older places Lighthouse 13.5 used: an `Agentmap:` line in robots.txt, a `link` element with `rel="ai-catalog"`, a `Link` response header, and `/.well-known/ai-catalog.json`. SeenLens does not yet read `rel="ard"` link elements or headers. | What SeenLens finds | Result | | --- | --- | | No signal and the path answers 404 or another non-200 status | Not applicable. Nothing to fix. | | No signal, but the path answers 200 with an HTML page | Fail. A catch-all route is faking a file. | | A signal, but the catalog does not load | Fail | | The file does not parse as JSON, or the content type is not JSON | Fail | | The file has errors in entries | Warn, titled 'has errors' | | The only gaps are missing displayName or representativeQueries | Warn, titled 'has gaps', low priority | | The file passes every rule | Pass | SeenLens applies these rules to the file. The root must be a JSON object with `specVersion` and an `entries` array. A top level `collections` member is an error. Each entry needs: - `identifier` in the form `urn:air:[:]:`. - `displayName`. - `type`, an agent resource media type such as `application/mcp-server-card+json`. A type SeenLens does not know gives a warning. - Exactly one of `url` or `data`. - `representativeQueries` with 2 to 5 sample queries. A missing list or another count gives a warning. - If present, `trustManifest` must be an object with an `identity`. ## What is the current status of the spec? The Agentic Resource Discovery (ARD) specification is a proposal. Version 0.91 is dated 2026-08-26 and its status is Proposal. The ARD project lists participants from Microsoft, Google, Hugging Face, GoDaddy and others, and licenses the work under Apache 2.0. The location moved. Version 0.91 names `/.well-known/ard.json` as the well known URI and `` as the HTML link. It calls `/.well-known/ai-catalog.json` and `rel="ai-catalog"` the predecessor, which consumers may also check. In the spec, `entries` is the only required top level member, and other top level members are ignored. Lighthouse followed. Its current `ard-schema` audit (Lighthouse 13.6.0, the latest npm release on 2026-11-06) reads `/.well-known/ard.json` and `rel="ard"`. It flags a manifest found only at the legacy location. The audit is not applicable when the site gives no signal and the path answers with a 4xx status. SeenLens follows the new location since rules 0.3.2: it checks `/.well-known/ard.json` first and the legacy `ai-catalog.json` only when ard.json is missing. To work with older and newer consumers, serve the same file at both paths and keep `specVersion` in it. Current Lighthouse ignores extra top level members. ## How can I check my catalog? ```text curl -sI https://example.com/.well-known/ai-catalog.json curl -s https://example.com/.well-known/ai-catalog.json | python3 -m json.tool | head -30 ``` Look at the status and the content type. A `text/html` type with status 200 means a catch-all page answers the path. Then check that the JSON parses. ## How do I fix it? If you have no agent resources to list, delete the file and make sure the path returns a real 404. See [soft 404 pages](https://seenlens.com/fixes/soft-404-unknown-urls) for catch-all routes. If you do run an MCP server or an agent, publish a valid catalog. This is a minimal file with one MCP server entry. Replace `example.com` with the domain you own. ```text { "specVersion": "1.0", "entries": [ { "identifier": "urn:air:example.com:server:search", "displayName": "Example search tool", "type": "application/mcp-server-card+json", "url": "https://example.com/mcp/server-card.json", "representativeQueries": [ "find articles about invoice templates", "search the Example help center" ] } ] } ``` The ARD spec requires the publisher part of `identifier` to be a fully qualified domain name. If you include a `trustManifest`, its `identity` must match that publisher domain. ### Next.js and static sites Place the file in `public/.well-known/ai-catalog.json`. Next.js serves static files from `public` with a type taken from the extension, which gives `application/json`. Copy it to `ard.json` in the same folder. ### Nginx ```text location = /.well-known/ai-catalog.json { default_type application/json; add_header Cache-Control "public, max-age=3600"; } ``` ### WordPress Create a `.well-known` folder in the site root and upload the file with SFTP. Check that your host and any security plugin do not block dot folders. Then request the URL and check the content type. ### Shopify The Shopify theme template documentation lists special templates for robots.txt, llms.txt, llms-full.txt and agents.md. It does not list one for `/.well-known` paths. A Shopify store without a proxy in front of it should return the default 404 and skip this check. ## How do I verify the fix? 1. Run the curl commands. The status must be 200, the content type must contain `json` and the JSON must print. 2. Scan the page with SeenLens. The check must pass, or show 'not applicable' if you removed the file. 3. Run Lighthouse with the Agentic Browsing category and read the ARD audit. See [Lighthouse agentic audit failures](https://seenlens.com/fixes/lighthouse-agentic-audit-failures). ## When can I ignore this check? Publish a catalog only if you run something agents can use, such as an MCP server or an A2A agent. A normal content site has nothing to list. A real 404 is the correct answer. SeenLens then marks the check not applicable. A fake or empty file is worse than none, because Lighthouse counts it as a failed audit. [Scan your page with SeenLens](https://seenlens.com/) ## Which checks are related? - [agent-card.json and other .well-known files](https://seenlens.com/fixes/well-known-agent-files) covers A2A cards, API catalogs and OAuth metadata. - [Add WebMCP tools](https://seenlens.com/fixes/add-webmcp-tools) covers tools that run in the browser. - [Lighthouse agentic audit failures](https://seenlens.com/fixes/lighthouse-agentic-audit-failures) covers the ARD audit in Lighthouse. ## Sources - [Agentic Resource Discovery specification](https://agenticresourcediscovery.org/spec/) (version 0.91, status Proposal, dated 2026-08-26; ard.json, entries, identifier and entry fields; checked 2026-11-06) - [Agentic Resource Discovery](https://agenticresourcediscovery.org/) (purpose, working group, Apache 2.0 license; checked 2026-11-06) - [Lighthouse 13.6.0 source, ard-schema audit](https://unpkg.com/lighthouse@13.6.0/core/audits/agentic/ard-schema.js) (ard.json and rel=ard, legacy location warning, not applicable rule; checked 2026-11-06) - [Shopify: theme templates](https://shopify.dev/docs/storefronts/themes/architecture/templates) (list of special templates; checked 2026-11-06)