# Embed: Troubleshooting

## Table of Contents

- [The iframe field is missing](#the-iframe-field-is-missing)
- [The iframe HTML renders blank or unstyled](#the-iframe-html-renders-blank-or-unstyled)
- [og:image is missing or low-resolution](#ogimage-is-missing-or-low-resolution)
  - [CLI Microlink API example](#cli-microlink-api-example)
  - [cURL Microlink API example](#curl-microlink-api-example)
  - [JavaScript Microlink API example](#javascript-microlink-api-example)
  - [Python Microlink API example](#python-microlink-api-example)
  - [Ruby Microlink API example](#ruby-microlink-api-example)
  - [PHP Microlink API example](#php-microlink-api-example)
  - [Golang Microlink API example](#golang-microlink-api-example)
- [The image works in the browser but not in \](#the-image-works-in-the-browser-but-not-in-)
- [The Embed SDK preview never loads](#the-embed-sdk-preview-never-loads)
- [Inconsistent results across runs](#inconsistent-results-across-runs)
- [Embed URL works in some contexts but not others](#embed-url-works-in-some-contexts-but-not-others)
- [Provider-specific quirks](#provider-specific-quirks)
- [Still stuck](#still-stuck)
- [Back to guides](#back-to-guides)

---

When an embed renders wrong, the cause is usually one of five things: the field you needed wasn't returned, the iframe HTML wasn't injected with its scripts, the source page hot-link-blocks `og:image`, the Embed SDK fetched too late, or the request needed auth or proxy.

For timeouts, blocked sites, auth/plan errors, and debug headers that apply to all workflows, see [common troubleshooting](https://microlink.io/docs/guides/common/troubleshooting).

## The iframe field is missing

Not every URL has an oEmbed endpoint. When discovery fails, the response has no `iframe` field — the rest of the metadata is still returned.

Plan for both shapes in your renderer:

```js
constembed=awaitmicrolink.embed(url)

if(embed){

container.innerHTML=embed.html

embed.scripts.forEach(injectScript)

}else{

container.innerHTML=renderCustomCard(awaitmicrolink.metadata(url))// fall back

}
```

The full provider list lives in the [iframe parameter reference](https://microlink.io/docs/api/parameters/iframe#providers-supported).

## The iframe HTML renders blank or unstyled

Twitter, Instagram, Reddit, and similar widgets need their script tag to actually paint. If you only inject `iframe.html`, you'll see a styled blockquote instead of the real widget.

Inject `iframe.scripts` too:

```js
embed.scripts.forEach(({src,async,charset})=>{

if(document.querySelector(`script[src="${src}"]`))return// dedupe

constscript=document.createElement('script')

script.src=src

if(async)script.async=true

if(charset)script.charset=charset

document.head.appendChild(script)

})
```

Dedupe matters because the same script (`platform.twitter.com/widgets.js`) gets returned for every Tweet embed on the page.

## og:image is missing or low-resolution

Many sites either skip `og:image` entirely or ship a small social-media-only thumbnail. Replace it with a real capture:

The following examples show how to use the Microlink API with CLI, cURL, JavaScript, Python, Ruby, PHP & Golang, targeting 'https://example.com/post' URL with 'screenshot' & 'embed' API parameters:

### CLI Microlink API example

```bash
microlink https://example.com/post&screenshot&embed=screenshot.url
```

### cURL Microlink API example

```bash
curl -G "https://api.microlink.io" \
  -d "url=https://example.com/post" \
  -d "screenshot=true" \
  -d "embed=screenshot.url"
```

### JavaScript Microlink API example

```javascript
import createClient from 'microlink.io'

const microlink = createClient()

const data = await microlink.screenshot('https://example.com/post')
```

### Python Microlink API example

```python
import requests

url = "https://api.microlink.io/"

querystring = {
    "url": "https://example.com/post",
    "screenshot": "true",
    "embed": "screenshot.url"
}

response = requests.get(url, params=querystring)

print(response.json())
```

### Ruby Microlink API example

```ruby
require 'uri'
require 'net/http'

base_url = "https://api.microlink.io/"

params = {
  url: "https://example.com/post",
  screenshot: "true",
  embed: "screenshot.url"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
response = http.request(request)

puts response.body
```

### PHP Microlink API example

```php
<?php

$baseUrl = "https://api.microlink.io/";

$params = [
    "url" => "https://example.com/post",
    "screenshot" => "true",
    "embed" => "screenshot.url"
];

$query = http_build_query($params);
$url = $baseUrl . '?' . $query;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET"
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    echo $response;
}
```

### Golang Microlink API example

```
package main

import (
    "fmt"
    "net/http"
    "net/url"
    "io"
)

func main() {
    baseURL := "https://api.microlink.io"

    u, err := url.Parse(baseURL)
    if err != nil {
        panic(err)
    }
    q := u.Query()
    q.Set("url", "https://example.com/post")
    q.Set("screenshot", "true")
    q.Set("embed", "screenshot.url")
    u.RawQuery = q.Encode()

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        panic(err)
    }

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}
```

```javascript
importcreateClientfrom'microlink.io'

constmicrolink=createClient()

constdata=awaitmicrolink.screenshot('https://example.com/post')
```

The API URL itself becomes the image. Use this in `<img src>` or `<meta property="og:image">`.

Or fall back inside your renderer:

```js
const{image}=awaitmicrolink.metadata(url)

constheroImage=image?.url??(awaitmicrolink.screenshot(url)).url
```

## The image works in the browser but not in \<img\>

Some sites block hot-linking based on `Referer`. The screenshot stays loadable from the browser's address bar but breaks inside another page's `<img>`.

Two options:

1.

    **Use `embed=image.url`** — this re-serves the asset through `api.microlink.io`, with permissive CORS and no referrer check.

    ```html
    <imgsrc="https://api.microlink.io?url=https://stripe.com&embed=image.url"/>
    ```

2.  **Use a screenshot capture instead** — Microlink renders the page itself, so the resulting image is hosted on Microlink's CDN and never re-requests the source.

    ```html
    <imgsrc="https://api.microlink.io?url=https://stripe.com&screenshot&meta=false&embed=screenshot.url"/>
    ```

## The Embed SDK preview never loads

The Embed SDK is lazy by default — it only fetches when the card enters the viewport. If you embed it inside a hidden tab, accordion, or `display: none` container, it never triggers.

Two fixes:

```jsx
// 1. Disable lazy when the container is conditionally hidden

<Microlinkurl='...'lazy={false}/>

// 2. Or expand the rootMargin so it fires earlier

<Microlinkurl='...'lazy={{rootMargin:'600px'}}/>
```

The `lazy` prop is covered on the [link preview component](https://microlink.io/link-preview) page.

## Inconsistent results across runs

If the same URL returns different metadata on different days, the cause is usually one of:

- **The source changed.** Default cache TTL is 24h. Pin to a fixed window with `ttl='7d'`.
- **The page is JS-rendered.** Some metadata only appears after hydration. The default rendering mode handles most cases, but for SPA-heavy targets you may need [waitForSelector](https://microlink.io/docs/api/parameters/waitForSelector) or [waitUntil](https://microlink.io/docs/api/parameters/waitUntil).
- **Different IP regions see different content.** Localized pricing, A/B tests, or geofences. Pin region with [proxy](https://microlink.io/docs/guides/common/proxy#geolocation-target-region-specific-content).

## Embed URL works in some contexts but not others

Slack, Discord, X, LinkedIn, and email clients each cache embed URLs differently. Common gotchas:

| Symptom                                             | Likely cause                                                                                                         |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| The image updated but Slack still shows the old one | Slack's image cache is sticky — change the URL by appending `&v=N`.                                                  |
| Twitter shows the title but no image                | Twitter Cards requires `meta` tags on **your** page, not on the API URL. Reference the embed URL in `twitter:image`. |
| Email client renders a placeholder                  | Many email clients block remote images by default. Use a screenshot capture and a stable URL.                        |

## Provider-specific quirks

A short list:

- **YouTube** — switch to `youtube-nocookie.com` after fetching by replacing the host inside `iframe.html` if you need cookieless embeds.
- **Spotify** — the Spotify embed expects fixed dimensions; pass `iframe={{ maxWidth: 600 }}` when discovery returns a too-narrow value.
- **X / Twitter** — Twitter sometimes returns a blockquote-only embed when the tweet is geo-restricted. Test with multiple URLs from different accounts.
- **Instagram** — the Instagram widget script is large; defer it until the first Instagram embed enters the viewport.

## Still stuck

Check the full [error codes reference](https://microlink.io/docs/api/basics/error-codes), the [iframe parameter reference](https://microlink.io/docs/api/parameters/iframe), the [embed parameter reference](https://microlink.io/docs/api/parameters/embed), or see [common troubleshooting](https://microlink.io/docs/guides/common/troubleshooting) for timeouts, auth, and plan errors.

## Back to guides

See the [guides overview](https://microlink.io/docs/guides) for more Microlink guides.