Skip to main content
Most issues come down to a handful of causes: the middleware isn’t deployed, the edge token is missing, the crawler wasn’t verified, or the serve mode is still shadow. Open the section that matches what you’re seeing.
If you’ve deployed the middleware and triggered an AI crawler but Agent Analytics is still empty, check each of the following in order.
1

Confirm the middleware is deployed

In Vercel, open your project and check the Functions tab. If middleware isn’t listed after a deploy, your middleware.ts file may not be at the root of your Next.js project, or the deployment that included it hasn’t finished. Redeploy and check again.
2

Confirm AEN_EDGE_TOKEN is set in Vercel

The token must be set as a Vercel environment variable — not just in a local .env file. Go to Vercel → your project → Settings → Environment Variables and confirm AEN_EDGE_TOKEN is present and non-empty. If it’s missing or empty, the middleware lets every request through and records nothing.
3

Trigger a real answer-engine crawler

Browsing your own site won’t create a hit: only visits from AI answer-engine crawlers are recorded. Open ChatGPT or Perplexity with browsing enabled and ask a question that makes it fetch a URL on your domain.
4

Know which visits are not recorded

Two kinds of visits never appear: crawlers Bluemoon does not recognise, and classic search bots. Googlebot, Bingbot and Applebot always receive your normal page and are never recorded — so if the only crawler that reached your page was Googlebot, Agent Analytics stays empty by design.
5

Verification does not decide whether a hit is counted

A recognised AI crawler is recorded whether or not it was verified. In Recent activity, verified visits show as Verified (IP_VERIFIED) and unverified ones as Unverified (UA_ONLY). Verification only decides whether the optimized version is served — not whether the hit is counted.
6

Check your middleware matcher

The default matcher covers all public pages but excludes _next/, api/, and favicon.ico. If the URL you tested falls outside the matcher’s scope, the middleware never runs for it.
If you’ve customised this matcher, make sure the URL you tested is still covered.
Recording a visit never delays your page. If the record is lost on the way, that visit won’t appear: test again with a fresh crawler request.
The middleware can record a crawler and still serve your normal page. Work through each of these.
1

Confirm the serve mode is default

The middleware ships in shadow mode: it records visits but always delivers your normal page. To serve the optimized version, switch to default and redeploy. With the copy-paste file, change the constant:
With the npm package, set AEN_SERVE_MODE=default in your environment variables. See Serve modes.
2

Confirm the crawler was verified

Only Verified visits (IP_VERIFIED) can receive the optimized version. An Unverified visit (UA_ONLY) — the crawler was recognised but not confirmed — always receives your normal page, even in default mode. Check the Verified column of Recent activity in Agent Analytics.
3

Check the crawler's purpose

Even a verified crawler is only served the optimized version if its purpose is USER_TRIGGERED or RETRIEVAL (User-triggered or Search / retrieval in Agent Analytics). Crawlers with other purposes, such as training crawlers, get your normal page. Why they came shows how many visits came for each purpose.
4

Check that the page has a fresh optimized version

A URL is only served the optimized version if one exists for that exact URL and its status is Optimized. Otherwise the crawler gets your normal page. In Agent Analytics, open See all pages → Your pages and check the URL’s status. If it is not Optimized, open it and click Regenerate, or use Generate missing.
All four conditions must hold at once: the serve mode is default, the crawler is verified (IP_VERIFIED), its purpose is USER_TRIGGERED or RETRIEVAL, and an optimized version marked Optimized exists for the URL. If any one fails, the crawler gets your normal page.
If requests pass through with nothing recorded, the middleware itself likely isn’t executing.
1

Verify the file name and location

Next.js only recognises the middleware when it is named exactly middleware.ts (or middleware.js) and placed at the root of your project — the same directory as package.json. Placing it inside src/, app/, pages/, or any other subdirectory makes Next.js ignore it silently.
2

Confirm you're deployed on Vercel

The copy-paste file runs on the Vercel Edge runtime. If you’ve customised your project’s runtime settings or are self-hosting outside Vercel, confirm the middleware appears under the project’s Functions tab after deploying. For Cloudflare, use the Cloudflare Worker.
3

Check that AEN_EDGE_TOKEN is non-empty

If AEN_EDGE_TOKEN is empty or undefined, the middleware does nothing: no detection, no recording, no serving. Confirm the variable is set in Vercel and that you redeployed after adding it.
If you’re testing locally with next dev, add AEN_EDGE_TOKEN to your .env.local. Production deployments read it from Vercel’s environment variables instead.
This is the most common concern for anyone new to serving alternate content to crawlers. The Agent Edge Network is designed to stay on the safe side of the cloaking line.
1

Search bots always get your normal page

Googlebot, Bingbot and Applebot always receive your normal page, without exception and whatever the serve mode.
2

Why this matters for AI Overviews

Google’s AI Overviews use the same crawl and index as Google Search. Serving Googlebot anything else would cloak Search itself. Because search bots always get your normal page, your Google rankings and AI Overview eligibility are unaffected.
3

Same content, different format

For the answer-engine crawlers that are served, the optimized version carries the same substance as your page, restructured into a format machines parse more reliably. It never adds anything your page doesn’t already say.
Serving a more machine-readable form of the same content to non-search answer engines is not cloaking — it is the same idea as a print stylesheet or an RSS feed. The substance is identical; only the format differs.
The optimized version is built from your page as it was at the time. If you’ve edited the page since, the version crawlers receive can lag behind the live page.
1

Use the Regenerate action

In Agent Analytics, open the page under See all pages → Your pages and click Regenerate. The optimized version is rebuilt from the current state of your page.
2

How out-of-date versions behave

Only versions marked Optimized are served; any other status means crawlers get your normal page instead. The case to watch for is a version still marked Optimized that was built before your edit: it keeps serving the older content until you regenerate it.
3

No redeploy needed

Once regenerated, the new version is served from the next qualifying crawler visit — no redeploy or cache purge on your side.
Still stuck? Review Serve modes to confirm your rollout stage, walk back through the Quickstart to re-check token and deployment steps, or contact support.