Troubleshooting

When a screenshot looks wrong, the cause is usually one of five things: the page was not ready yet, the wrong area was captured, the request ran out of time, the site blocked automation, or the request used the wrong auth or plan setup.

For timeouts, blocked sites, auth/plan errors, and debug headers that apply to all workflows, see common troubleshooting.

Start with a fast navigation event, then wait for the exact piece of content you care about:

microlink https://dev.to&screenshot&waitUntil=domcontentloaded&waitForSelector=h1

curl -G "https://api.microlink.io" \
  -d "url=https://dev.to" \
  -d "screenshot=true" \
  -d "meta=false" \
  -d "waitUntil=domcontentloaded" \
  -d "waitForSelector=h1"

import mql from '@microlink/mql'

const { data } = await mql('https://dev.to', {
  screenshot: true,
  meta: false,
  waitUntil: "domcontentloaded",
  waitForSelector: "h1"
})

import requests

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

querystring = {
    "url": "https://dev.to",
    "screenshot": "true",
    "meta": "false",
    "waitUntil": "domcontentloaded",
    "waitForSelector": "h1"
}

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

print(response.json())

require 'uri'
require 'net/http'

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

params = {
  url: "https://dev.to",
  screenshot: "true",
  meta: "false",
  waitUntil: "domcontentloaded",
  waitForSelector: "h1"
}

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

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

$params = [
    "url" => "https://dev.to",
    "screenshot" => "true",
    "meta" => "false",
    "waitUntil" => "domcontentloaded",
    "waitForSelector" => "h1"
];

$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;
}

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://dev.to")
    q.Set("screenshot", "true")
    q.Set("meta", "false")
    q.Set("waitUntil", "domcontentloaded")
    q.Set("waitForSelector", "h1")
    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))
}

import mql from '@microlink/mql'

const { data } = await mql('https://dev.to', {
  screenshot: true,
  meta: false,
  waitUntil: "domcontentloaded",
  waitForSelector: "h1"
})

If you are using screenshot.element, remember that Microlink already waits for that element to be visible before it captures.

If the capture is technically correct but cluttered, clean it first with adblock, click, or styles.

If you use screenshot.overlay.background and the request fails with EINVALOVERLAYBG, the background value is malformed.

Valid examples:

{ background: '#F76698' }
{ background: 'rgba(0, 0, 0, 0.8)' }
{ background: 'linear-gradient(0deg, #330867 0%, #30CFD0 100%)' }

The most common problems are missing gradient color stops, invalid color values, or malformed CSS syntax.

Check the full error codes reference or see common troubleshooting for timeout, auth, and plan errors.

See the guides overview for more Microlink guides.