# Troubleshoot a preview

> Fix missing Open Graph metadata, HTTP errors, JavaScript-only pages, timeouts, and blocked URLs in server-side link previews.

Start with the response status and the HTML the server actually returns. A page that looks right in your browser may send different metadata to a preview fetcher.

## Missing title or image

Missing metadata is returned as `null`. The fast preset reads up to 30,000 decoded bytes and stops after the head. If `result.truncated` is `true`, the head was longer than that (large inline CSS or scripts) and later tags were not read: raise `maxBytes`. If metadata lives in body JSON-LD, try `presets.quality`, which allows 200,000 bytes and body fallbacks.

```ts
import { preview, presets } from "linkpeek";

const result = await preview(url, presets.quality);
const title = result.title ?? result.siteName;
```

Quality mode still doesn't run JavaScript. If the HTML the server sends has no metadata at all, you need a browser-rendering service or the provider's API. If you already have the HTML, [`parseHTML()`](https://linkpeek.js.org/guides/open-graph-parser/) lets you test parsing on its own, without fetching.

## HTTP errors and bot blocks

An HTML response with a 403, 404 or 500 status can still produce metadata. `preview()` resolves with that status; an HTTP error alone does not throw. Check `statusCode` before caching a preview.

```ts
const result = await preview(url);
if (result.statusCode >= 400) {
  // Show a hostname fallback and skip caching this response.
}
```

Bot challenges, rate limits and access restrictions can prevent server-side fetching. Respect the target’s access policy, use an appropriate `userAgent`, and cache successful results. Do not send user cookies or service credentials to a target URL.

## Timeouts and cancellation

The default timeout is 8,000 milliseconds for the whole call, including redirects and a meta-refresh hop. A timeout throws `LinkpeekError` with code `TIMEOUT`; DNS, connection and TLS failures throw `FETCH_FAILED` with the original error as `cause`. Set a budget that fits your endpoint; do not retry indefinitely. A caller abort rethrows the signal's reason.

```ts
import { LinkpeekError, preview } from "linkpeek";

try {
  const result = await preview(url, { timeout: 5_000 });
  console.log(result.title);
} catch (error) {
  if (error instanceof LinkpeekError) {
    console.log(error.code);
  }
  // Return your application's fallback card.
}
```

## Blocked URLs

`PRIVATE_NETWORK_BLOCKED` means the target matched a blocked hostname or literal address, or a `resolveHost` lookup returned a private address. Single-label hosts such as `http://intranet/` and names under `.internal`, `.local`, `.localdomain`, `.intranet`, `.private`, `.corp`, `.home`, `.lan` or `.home.arpa` count as internal. Keep private access disabled on public endpoints. For an intentionally internal, trusted workflow, review [the security model](https://linkpeek.js.org/security/) before using `allowPrivateIPs`.

`SENSITIVE_HEADER` means a custom header carries credentials. Remove it. A custom `fetch` must honor manual redirects and abort signals so target checks remain effective.

## Browser or server?

Call `preview()` on a server or an edge worker. Browsers won't let a page fetch another site's HTML (CORS). The synchronous `parseHTML()` parses an HTML string without fetching, which is how the [parser example](https://linkpeek.js.org/guides/open-graph-parser/#try) runs in your browser.

## Report a metadata mismatch

Include the package version, options, expected fields and a minimal HTML sample. Remove credentials and private content. A fixture that reproduces the problem tells a parser bug apart from a site that changed its response.

Related: [Security model](https://linkpeek.js.org/security/) · [Error codes](https://linkpeek.js.org/api/#errors) · [Open Graph parser](https://linkpeek.js.org/guides/open-graph-parser/) · [Open an issue](https://github.com/thegruber/linkpeek/issues/new/choose)
