Troubleshooting Fresh

Common problems and their solutions. Start from the symptom you are seeing.

CORS Errors

Symptom: AI agents or validators report a CORS error when fetching your file. Browser console shows Access to fetch at 'https://yourdomain.com/.well-known/reasoning.json' from origin '...' has been blocked by CORS policy.

Cause: The server is not returning Access-Control-Allow-Origin: * on the response.

Fix: Add the CORS header to your server configuration for the .well-known/reasoning.json path specifically:

# Nginx
location /.well-known/reasoning.json {
    add_header Access-Control-Allow-Origin *;
}

# Apache
<Files "reasoning.json">
    Header set Access-Control-Allow-Origin "*"
</Files>

Verify the fix:

curl -I -H "Origin: https://test.com" https://yourdomain.com/.well-known/reasoning.json
# Look for: Access-Control-Allow-Origin: *

Note: Access-Control-Allow-Origin: * is the correct value. A specific origin (like Access-Control-Allow-Origin: https://perplexity.ai) will not work - it must be the wildcard.

---

Validator Shows v1.0 to v1.1 Migration Needed

Symptom: The ARP validator reports Deprecated field pattern detected: false_claim/correction_fact. Migrate to trigger_topic/verified_fact (v1.1+).

Cause: Your file is using the v1.0 corrections format. v1.1 renamed the fields.

Fix: Replace every instance of false_claim with trigger_topic and every instance of correction_fact with verified_fact in your corrections array:

// Before (v1.0)
{
  "corrections": [
    {
      "false_claim": "Company was founded in 2010",
      "correction_fact": "Company was founded in 2015"
    }
  ]
}

// After (v1.1+)
{
  "corrections": [
    {
      "trigger_topic": "Company founding date",
      "verified_fact": "The company was founded in 2015."
    }
  ]
}

Also update your $schema URL to point to v1.1 or v1.2 and set "version": "1.1" or "version": "1.2".

---

File Not Discovered by AI Agents

Symptom: You have deployed reasoning.json but AI agents do not appear to be using the content. Responses about your organization still contain errors that your corrections address.

There are three sub-causes with different fixes:

Sub-cause 1: Indexing latency

AI systems that rely on web crawling can take 24-72 hours to crawl and index a newly deployed reasoning.json. This is expected behavior. Wait at least 72 hours before concluding the file is not being discovered.

Sub-cause 2: File not at the correct path

Confirm the file is accessible at exactly /.well-known/reasoning.json (not /reasoning.json, not /.well-known/arp.json):

curl -s https://yourdomain.com/.well-known/reasoning.json | head -5
# Should return JSON starting with { "$schema": ...

If the command returns an HTML error page, the path is wrong or the server is not configured to serve the file.

Sub-cause 3: HTML discovery tag missing

Some AI crawlers use the HTML link tag to find the file rather than guessing the well-known path. Add this to your head section:

<link rel="reasoning" type="application/json" href="/.well-known/reasoning.json" />

Sub-cause 4: llms.txt not referencing the file

AI systems that process llms.txt may prioritize files listed there. Add a line:

- /.well-known/reasoning.json: ARP entity facts and corrections for AI reasoning agents

---

Signature Verification Fails

Symptom: The validator reports Signature verification failed or DNS TXT record not found for a v1.2 signed file.

Sub-cause 1: DNS TXT record not yet propagated

DNS changes take up to 48 hours to propagate globally. After publishing your DNS TXT record, wait at least 24 hours before testing signature verification.

Check propagation:

dig TXT arp-default._arp.yourdomain.com
# Should return the TXT record value

If dig returns no records, DNS has not propagated yet. If it returns a record but verification still fails, the record value is malformed.

Sub-cause 2: Selector name mismatch

The selector value in your signing block must exactly match the DNS record name prefix. If your signing.selector is "default", the DNS record must be at arp-default._arp.yourdomain.com. If it is "primary", the record must be at arp-primary._arp.yourdomain.com.

// In reasoning.json
"signing": {
    "selector": "default"
}
// DNS record name must be: arp-default._arp.yourdomain.com

Sub-cause 3: JCS canonicalization not used

The signature must be computed over the JCS (JSON Canonicalization Scheme, RFC 8785) canonical form of the file, with the signing.signature field excluded. If you computed the signature over the raw JSON bytes or used a different serialization, verification will fail.

Use the ARP CLI to sign correctly:

npx arp-validator sign ./reasoning.json --key ./private.key --selector default

Sub-cause 4: File modified after signing

Any modification to the file after signing invalidates the signature. If you update the file, you must re-sign it.

---

File Too Large (Exceeds 100 KB Limit)

Symptom: Validator reports File size exceeds maximum allowed size of 100 KB or AI agents appear to silently reject the file.

Cause: The file has grown too large, usually due to extensive corrections arrays or verbose field values.

Fix: Audit your file against the anti-spam character limits:

Field	Limit	Common violation
elevator_pitch	500 chars	Paragraph-length prose
Single verified_fact	300 chars	Multiple sentences
framing_context	1000 chars	Multiple paragraphs
Single recommendation_context item	200 chars	Detailed explanations

Trim each field to its limit. If you have more than 20 corrections entries, review whether all are addressing genuinely common hallucination patterns or if some can be merged.

Also check for inadvertently duplicated sections - copy-paste errors can double the file size.

---

SPA Catch-All Returns HTML Instead of JSON

Symptom: curl https://yourdomain.com/.well-known/reasoning.json returns your index.html page with a 200 status code, not JSON.

Cause: Single-page applications (React, Next.js, Vue, Angular) typically use a catch-all route to serve index.html for all unmatched paths. The .well-known/reasoning.json path is matching this catch-all.

Fix: Configure your router or hosting platform to serve the static JSON file before the catch-all route applies.

Next.js (App Router) - public/.well-known/reasoning.json:

Place the file in the public directory at public/.well-known/reasoning.json. Next.js serves public/ as static files before applying routing. Add CORS headers in next.config.js:

// next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/.well-known/reasoning.json',
        headers: [
          { key: 'Access-Control-Allow-Origin', value: '*' },
          { key: 'Content-Type', value: 'application/json' }
        ]
      }
    ]
  }
}

Vercel - vercel.json:

{
  "headers": [
    {
      "source": "/.well-known/reasoning.json",
      "headers": [
        { "key": "Access-Control-Allow-Origin", "value": "*" },
        { "key": "Content-Type", "value": "application/json" }
      ]
    }
  ]
}

Nginx reverse proxy:

Add a location block that takes priority over the proxy_pass catch-all:

location = /.well-known/reasoning.json {
    root /var/www/static;
    add_header Access-Control-Allow-Origin *;
    add_header Content-Type application/json;
}

---

AI Still Hallucinating After Deployment

Symptom: You deployed reasoning.json, waited 72 hours, but AI responses still contain the errors your corrections address.

Work through these checks in order:

Check 1: Confirm the file is live and valid

curl -s https://yourdomain.com/.well-known/reasoning.json | python -m json.tool > /dev/null && echo "Valid JSON" || echo "Invalid JSON"

Check 2: Confirm CORS headers are present

curl -I -H "Origin: https://test.com" https://yourdomain.com/.well-known/reasoning.json | grep -i "access-control"

Check 3: Review trigger_topic phrasing

The trigger_topic field describes the category of question that should trigger the correction. Overly narrow phrasing may not match the queries the AI is processing. Compare:

• Too narrow: "trigger_topic": "Nordlicht GmbH Germany lighting"
• Better: "trigger_topic": "Nordlicht lighting or lamps"

The trigger topic should match how someone would phrase a question about the hallucination, not a description of the hallucination itself.

Check 4: Confirm the AI platform you are testing uses web retrieval

AI models that rely purely on training data (without real-time web retrieval) will not be affected by reasoning.json until they are retrained on updated crawl data. Test with Perplexity or Bing Copilot, which do heavy real-time retrieval, to get the fastest feedback on whether the file is being consumed.

Check 5: Test with direct document injection

As a diagnostic, copy the contents of your reasoning.json into a system prompt or user message and ask the AI the same question. If the AI responds correctly with the file contents explicitly provided, the problem is retrieval - the AI is not finding your file. If the AI still responds incorrectly even with the file explicitly provided, the problem is in the corrections structure itself.

Check 6: Increase correction redundancy

If a single correction entry is not changing AI behavior, try adding the same correction in multiple formulations with different trigger topic phrasing. Redundant corrections for the same fact increase the probability that at least one matches the AI's query interpretation.