An audit reports a meta description outside the <head>. The browser shows the correct title, while a shared URL produces an unsuitable preview. These observations may have different causes. With Next.js, first establish which response each recipient receives.
The App Router can send metadata after the initial interface. For certain bots, Next.js instead waits for metadata and places it in the head. Inspecting one source response is therefore insufficient to classify streaming as a defect or establish that delivery works for every recipient.
This workflow investigates that delivery. It includes an explicitly hypothetical test plan, without reporting measurements from a customer website. Canonical changes after hydration and error-page handling require their own diagnoses.
What can arrive later
Next.js has supported streaming in generateMetadata since version 15.2. The 15.2 release announcement explains the reason: an asynchronous metadata request should not invariably hold back an interface that is otherwise ready to send.
The current generateMetadata documentation states that resolved streaming metadata is appended to the body. For bots that execute JavaScript and inspect the full DOM, Next.js specifically names Googlebot as a verified example. This is a documented framework behavior. It does not establish that Google has fetched, processed or indexed your particular URL.
A title tag in an unexpected location is therefore initially a delivery finding. Check its value, the number of corresponding elements and the recipient as well. A correct title delivered later and two conflicting titles are different problems.
Support for streaming also does not mean every route visibly delays its metadata. Static or quickly resolved data may already be available. Caching and the route's rendering model affect what a particular request returns.
Preserve three different records
A complete HTTP body shows which bytes arrived during a fetch. Without additional recording, it does not give you a precise timeline of their arrival. Nor is it identical to the DOM subsequently constructed by a browser.
Keep these records separate: the full server response, arrival timing where needed, and browser output. A saved DOM may contain metadata missing from the first response segment. Conversely, a truncated terminal preview may overlook a meta description that was delivered successfully.
Do not search only for the page title's text. The same words may appear in a heading or serialized data block. You need the actual metadata element and its attributes. Then check for further occurrences, so one correct match cannot conceal a conflicting second entry.
Include the version in the finding
Establish the Next.js version in the deployed build. A local package.json version range does not reliably establish that fact. The lockfile, build artifact and deployment need to agree. Within the relevant project directory, one way to read the installed version is:
bashnode -p "require('next/package.json').version"
Record the route, App Router, rendering configuration and custom Next configuration too. A development server does not replace a test of the corresponding production build. An older version without streaming support also requires a different explanation from a recent build intentionally using it.
This guide was checked against official documentation on November 3, 2026. We also use the bot list pinned to Next.js v16.4.5 as a concrete source reference. Consult the matching tag for your installation. The moving canary development branch does not automatically describe the package running on your site.
Which bots receive blocking metadata
Next.js uses the User-Agent header to decide which recipients are treated as HTML-limited. For these recipients, output waits for metadata, which then appears in the head. The htmlLimitedBots reference explains the selection and configuration option.
The list includes preview bots. This matters for Open Graph, because a shared-link preview can depend on a different request from your browser's page display. Seeing an appropriate image in your browser does not establish that a particular preview service received the intended metadata response.
Do not treat “Google” as one user agent either. The v16.4.5 bot-classification source distinguishes the main Googlebot using DOM processing from other Google crawlers. The exact list and decision in your build matter. A result for one Google service should not be generalized across all of them without checking.
A user agent you supply yourself tests response selection for that string. It does not establish a genuine visit by the named service. Network restrictions, access controls and other infrastructure may additionally affect a real bot request.
Capture complete GET responses
Start with a public URL requiring no login. The following address is fictional. These commands save headers and the complete body separately, but do not execute JavaScript:
bashcurl --compressed -sS -A 'Mozilla/5.0' -D browser.headers -o browser.html 'https://example.com/articles/test'
curl --compressed -sS -A 'Googlebot/2.1 (+http://www.google.com/bot.html)' -D googlebot.headers -o googlebot.html 'https://example.com/articles/test'
curl --compressed -sS -A 'Twitterbot/1.0' -D preview.headers -o preview.html 'https://example.com/articles/test'
On Windows, use curl.exe where necessary to invoke curl itself. The commands deliberately do not follow redirects automatically. If one occurs, document it and inspect the final URL separately. Otherwise, you may compare metadata from an intermediate response with metadata from the article.
Check the status and content type first. A challenge page returning 200 is not a successful article response. Then inspect the saved HTML files in full, including head, body and relevant tags. A HEAD request cannot supply this body evidence.
Repeat the requests with comparable cache states and without changing session data. Record available cache headers and the observation time. One different response could result from an older cache entry or another variant. It does not yet establish a particular bot-selection rule.
What demonstrates streaming
A tag's location in saved HTML describes its structure. Claiming that metadata arrived later additionally requires an arrival record. In a suitable test environment, you can capture a curl trace using --trace-time --trace-ascii arrival.trace, for example. These files may contain response content and sensitive headers, so use the public, sanitized test route.
A server or proxy may buffer small response segments. One observed arrival block therefore does not establish that the application did not attempt to stream internally. Investigate the path to the recipient. Conversely, Transfer-Encoding: chunked alone does not demonstrate that metadata specifically arrived later. HTTP/2 uses DATA frames and does not permit that chunked transfer encoding. The HTTP/1.1 header is therefore not a required indicator of streaming.
This distinction matters for server-side rendering: generated on the server does not necessarily mean complete in the first response segment. Establish which information each recipient receives, when it arrives and how it is represented.
A hypothetical comparison with a controlled delay
Suppose a test route obtains metadata from a slow data source. The following experiment is a plan, not a reported test. The team uses an isolated production build and known test content. It changes neither customer data nor caching across the entire application.
First, record an undelayed control and the intended metadata values. Then delay only the test data source used by generateMetadata. The route must actually use suitable dynamic output in the build under investigation. An already complete prerendered response cannot demonstrate request-time metadata streaming.
| Case | Observation to record | Limit of the result |
|---|---|---|
| Ordinary browser user agent | Order of interface and metadata arrival | No visible delay may reflect caching or buffering |
| Googlebot user agent | Full response and resulting DOM in a separate rendering test | curl itself does not execute JavaScript |
| HTML-limited preview user agent | Metadata in the appropriate response's head | The service's actual preview needs a separate check |
| Changed bot rule in the isolated build | Whether the documented selection change occurs | Configuration must be rebuilt and deployed |
If Cache Components are enabled, include their generateMetadata rules too. Current documentation distinguishes runtime data, uncached data access and routes otherwise fully prerendered. Do not transfer an experiment from another configuration unchanged. Record why the test route waits for metadata at request time in this particular build.
When the comparison contradicts expectations
If the intended tags are absent from every complete response, start with the metadata function and its data source. Check errors, empty returns and the route that actually executed. An expected value inside a JavaScript data block is not an emitted HTML metadata element. Waiting longer alone cannot create a missing element.
If only the preview request behaves unexpectedly, compare its exact user-agent string with the effective regex. Then inspect the deployment and upstream response variants. A configuration entry in your working directory is insufficient when another build is being served. Switching all bots to blocking treatment may merely hide that cause.
If tags are delivered correctly but a preview stays old, distinguish a fresh page request from the preview service's stored result. Record when that service actually requested the URL again, where its tools or your logs expose this. Without that observation, you do not yet know whether you are assessing the changed response or an older preview.
A custom regex does not add one entry
Setting a htmlLimitedBots regex replaces the default list. It does not automatically extend it. Specifying only a custom preview bot can remove previously included recipients from blocking treatment. Document the complete intended selection and retest the relevant existing bots.
Next.js documents htmlLimitedBots: /.*/ as disabling metadata streaming altogether. It can support a limited comparison in an isolated test. Using it as a blanket production correction requires considering the tradeoff: waiting for slow metadata can lengthen response times for ordinary visitors too.
Before changing the rule, inspect the metadata source itself. Are stable values loaded unnecessarily slowly? Does caching fit the content? Does the function return the right values at all? A blocking response with the wrong description still has the wrong description. Position alone does not resolve those questions.
Close the audit finding with reproducible evidence
Organize the affected URL inventory through Crawl Foundry's technical Site Audit workflow. Add saved responses and the user-agent comparison to the finding. A general crawl observation does not replace a version-specific investigation of this response selection.
Our article on working through technical audit findings helps prepare the handoff. Include URL, release, user agent, cache state, expected values and the precise difference. This separates missing tags, incorrect values and an expected streaming location.
For JavaScript rendering, the resulting DOM then requires its own check. After approval, repeat the same observations against the deployed version. For broader changes, include the selection in your SEO migration verification.
A resolved finding describes behavior for the recipients tested. A service's actual preview, Google's processing and later search performance are further observations. Correct framework configuration alone cannot establish them.