Skip to Content

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.

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() 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.

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.

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 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 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.