## Table of Contents

- [PDF: Troubleshooting](#pdf-troubleshooting)
- [The PDF layout looks wrong](#the-pdf-layout-looks-wrong)
  - [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 PDF is missing content or printed too early](#the-pdf-is-missing-content-or-printed-too-early)
  - [CLI Microlink API example](#cli-microlink-api-example-1)
  - [cURL Microlink API example](#curl-microlink-api-example-1)
  - [JavaScript Microlink API example](#javascript-microlink-api-example-1)
  - [Python Microlink API example](#python-microlink-api-example-1)
  - [Ruby Microlink API example](#ruby-microlink-api-example-1)
  - [PHP Microlink API example](#php-microlink-api-example-1)
  - [Golang Microlink API example](#golang-microlink-api-example-1)
- [Still stuck](#still-stuck)
- [Back to guides](#back-to-guides)

---

[API](https://microlink.io/docs/api/getting-started/overview)

[GUIDES](https://microlink.io/docs/guides) [MQL](https://microlink.io/docs/mql/getting-started/overview) [SDK](https://microlink.io/docs/sdk/getting-started/overview) [CARDS](https://microlink.io/docs/cards/getting-started/overview)

API GUIDES MQL SDK CARDS

Getting Started

[Overview](https://microlink.io/docs/guides)

[What is Microlink](https://microlink.io/docs/guides/what-is-microlink)

[Screenshot](https://microlink.io/docs/guides/screenshot)

[Customizing output](https://microlink.io/docs/guides/screenshot/customizing-output)

[Browser settings](https://microlink.io/docs/guides/screenshot/browser-settings)

[Page interaction](https://microlink.io/docs/guides/screenshot/page-interaction)

[Delivery and embedding](https://microlink.io/docs/guides/screenshot/embedding)

[Caching and performance](https://microlink.io/docs/guides/screenshot/caching-and-performance)

[Private pages](https://microlink.io/docs/guides/screenshot/private-pages)

[Troubleshooting](https://microlink.io/docs/guides/screenshot/troubleshooting)

[Data extraction](https://microlink.io/docs/guides/data-extraction)

[Defining rules](https://microlink.io/docs/guides/data-extraction/defining-rules)

[Page preparation](https://microlink.io/docs/guides/data-extraction/page-preparation)

[Delivery and response shaping](https://microlink.io/docs/guides/data-extraction/delivery-and-response)

[Caching and performance](https://microlink.io/docs/guides/data-extraction/caching-and-performance)

[Private pages](https://microlink.io/docs/guides/data-extraction/private-pages)

[Troubleshooting](https://microlink.io/docs/guides/data-extraction/troubleshooting)

[Embed](https://microlink.io/docs/guides/embed)

[SDK](https://microlink.io/docs/guides/embed/sdk)

[Iframe parameter](https://microlink.io/docs/guides/embed/iframe)

[Custom HTML/CSS](https://microlink.io/docs/guides/embed/metadata-api)

[Custom previews with AI](https://microlink.io/docs/guides/embed/custom-previews-with-ai)

[Caching and performance](https://microlink.io/docs/guides/embed/caching-and-performance)

[Private pages and proxy](https://microlink.io/docs/guides/embed/private-pages-and-proxy)

[Troubleshooting](https://microlink.io/docs/guides/embed/troubleshooting)

[Markdown](https://microlink.io/docs/guides/markdown)

[Choosing scope](https://microlink.io/docs/guides/markdown/choosing-scope)

[Delivery and response shaping](https://microlink.io/docs/guides/markdown/delivery-and-response)

[Function](https://microlink.io/docs/guides/function)

[Writing functions](https://microlink.io/docs/guides/function/writing-functions)

[Browser interaction](https://microlink.io/docs/guides/function/browser-interaction)

[Profiling and performance](https://microlink.io/docs/guides/function/profiling-and-performance)

[Troubleshooting](https://microlink.io/docs/guides/function/troubleshooting)

[PDF](https://microlink.io/docs/guides/pdf)

[Page size and layout](https://microlink.io/docs/guides/pdf/page-size-and-layout)

[Page preparation](https://microlink.io/docs/guides/pdf/page-preparation)

[Delivery and embedding](https://microlink.io/docs/guides/pdf/embedding)

[Caching and performance](https://microlink.io/docs/guides/pdf/caching-and-performance)

[Private pages](https://microlink.io/docs/guides/pdf/private-pages)

[Troubleshooting](https://microlink.io/docs/guides/pdf/troubleshooting)

[Metadata](https://microlink.io/docs/guides/metadata)

[Choosing fields](https://microlink.io/docs/guides/metadata/choosing-fields)

[Extending results](https://microlink.io/docs/guides/metadata/extending-results)

[Delivery and response shaping](https://microlink.io/docs/guides/metadata/delivery-and-response)

[Page preparation](https://microlink.io/docs/guides/metadata/page-preparation)

[Caching and performance](https://microlink.io/docs/guides/metadata/caching-and-performance)

[Private pages](https://microlink.io/docs/guides/metadata/private-pages)

[Troubleshooting](https://microlink.io/docs/guides/metadata/troubleshooting)

[Insights](https://microlink.io/docs/guides/insights)

[Technology detection](https://microlink.io/docs/guides/insights/technology-detection)

[Lighthouse reports](https://microlink.io/docs/guides/insights/lighthouse-reports)

[Caching and performance](https://microlink.io/docs/guides/insights/caching-and-performance)

[Troubleshooting](https://microlink.io/docs/guides/insights/troubleshooting)

[Common patterns](https://microlink.io/docs/guides/common/caching)

[Caching patterns](https://microlink.io/docs/guides/common/caching)

[Private pages](https://microlink.io/docs/guides/common/private-pages)

[Proxy](https://microlink.io/docs/guides/common/proxy)

[Troubleshooting](https://microlink.io/docs/guides/common/troubleshooting)

[Production patterns](https://microlink.io/docs/guides/common/production-patterns)

API GUIDES MQL SDK CARDS

Getting Started

[Overview](https://microlink.io/docs/guides)

[What is Microlink](https://microlink.io/docs/guides/what-is-microlink)

[Screenshot](https://microlink.io/docs/guides/screenshot)

[Customizing output](https://microlink.io/docs/guides/screenshot/customizing-output)

[Browser settings](https://microlink.io/docs/guides/screenshot/browser-settings)

[Page interaction](https://microlink.io/docs/guides/screenshot/page-interaction)

[Delivery and embedding](https://microlink.io/docs/guides/screenshot/embedding)

[Caching and performance](https://microlink.io/docs/guides/screenshot/caching-and-performance)

[Private pages](https://microlink.io/docs/guides/screenshot/private-pages)

[Troubleshooting](https://microlink.io/docs/guides/screenshot/troubleshooting)

[Data extraction](https://microlink.io/docs/guides/data-extraction)

[Defining rules](https://microlink.io/docs/guides/data-extraction/defining-rules)

[Page preparation](https://microlink.io/docs/guides/data-extraction/page-preparation)

[Delivery and response shaping](https://microlink.io/docs/guides/data-extraction/delivery-and-response)

[Caching and performance](https://microlink.io/docs/guides/data-extraction/caching-and-performance)

[Private pages](https://microlink.io/docs/guides/data-extraction/private-pages)

[Troubleshooting](https://microlink.io/docs/guides/data-extraction/troubleshooting)

[Embed](https://microlink.io/docs/guides/embed)

[SDK](https://microlink.io/docs/guides/embed/sdk)

[Iframe parameter](https://microlink.io/docs/guides/embed/iframe)

[Custom HTML/CSS](https://microlink.io/docs/guides/embed/metadata-api)

[Custom previews with AI](https://microlink.io/docs/guides/embed/custom-previews-with-ai)

[Caching and performance](https://microlink.io/docs/guides/embed/caching-and-performance)

[Private pages and proxy](https://microlink.io/docs/guides/embed/private-pages-and-proxy)

[Troubleshooting](https://microlink.io/docs/guides/embed/troubleshooting)

[Markdown](https://microlink.io/docs/guides/markdown)

[Choosing scope](https://microlink.io/docs/guides/markdown/choosing-scope)

[Delivery and response shaping](https://microlink.io/docs/guides/markdown/delivery-and-response)

[Function](https://microlink.io/docs/guides/function)

[Writing functions](https://microlink.io/docs/guides/function/writing-functions)

[Browser interaction](https://microlink.io/docs/guides/function/browser-interaction)

[Profiling and performance](https://microlink.io/docs/guides/function/profiling-and-performance)

[Troubleshooting](https://microlink.io/docs/guides/function/troubleshooting)

[PDF](https://microlink.io/docs/guides/pdf)

[Page size and layout](https://microlink.io/docs/guides/pdf/page-size-and-layout)

[Page preparation](https://microlink.io/docs/guides/pdf/page-preparation)

[Delivery and embedding](https://microlink.io/docs/guides/pdf/embedding)

[Caching and performance](https://microlink.io/docs/guides/pdf/caching-and-performance)

[Private pages](https://microlink.io/docs/guides/pdf/private-pages)

[Troubleshooting](https://microlink.io/docs/guides/pdf/troubleshooting)

[Metadata](https://microlink.io/docs/guides/metadata)

[Choosing fields](https://microlink.io/docs/guides/metadata/choosing-fields)

[Extending results](https://microlink.io/docs/guides/metadata/extending-results)

[Delivery and response shaping](https://microlink.io/docs/guides/metadata/delivery-and-response)

[Page preparation](https://microlink.io/docs/guides/metadata/page-preparation)

[Caching and performance](https://microlink.io/docs/guides/metadata/caching-and-performance)

[Private pages](https://microlink.io/docs/guides/metadata/private-pages)

[Troubleshooting](https://microlink.io/docs/guides/metadata/troubleshooting)

[Insights](https://microlink.io/docs/guides/insights)

[Technology detection](https://microlink.io/docs/guides/insights/technology-detection)

[Lighthouse reports](https://microlink.io/docs/guides/insights/lighthouse-reports)

[Caching and performance](https://microlink.io/docs/guides/insights/caching-and-performance)

[Troubleshooting](https://microlink.io/docs/guides/insights/troubleshooting)

[Common patterns](https://microlink.io/docs/guides/common/caching)

[Caching patterns](https://microlink.io/docs/guides/common/caching)

[Private pages](https://microlink.io/docs/guides/common/private-pages)

[Proxy](https://microlink.io/docs/guides/common/proxy)

[Troubleshooting](https://microlink.io/docs/guides/common/troubleshooting)

[Production patterns](https://microlink.io/docs/guides/common/production-patterns)

## PDF: Troubleshooting

[Copy for LLM](https://microlink.io/docs/guides/pdf/troubleshooting.md "Copy content for LLM")

\|

[View as Markdown](https://microlink.io/docs/guides/pdf/troubleshooting.md "View content as Markdown")

When a generated PDF looks wrong, the cause is usually one of five things: the print layout is wrong, the page was not ready yet, 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](https://microlink.io/docs/guides/common/troubleshooting).

## The PDF layout looks wrong

Pick the control that matches the problem:

| Problem                                        | Best fix                   |
| ---------------------------------------------- | -------------------------- |
| You need a standard printable document size    | `pdf.format`               |
| You need exact custom page dimensions          | `pdf.width` + `pdf.height` |
| You need a wide document                       | `pdf.landscape`            |
| You need more whitespace around the content    | `pdf.margin`               |
| You need more or less content per page         | `pdf.scale`                |
| You want on-screen design instead of print CSS | `mediaType: 'screen'`      |
| You only need part of the final document       | `pdf.pageRanges`           |

A common fix is to keep the paper format but switch to screen CSS and add predictable margins:

The following examples show how to use the Microlink API with CLI, cURL, JavaScript, Python, Ruby, PHP & Golang, targeting 'https://blog.alexmaccaw.com/advice-to-my-younger-self' URL with 'pdf', 'mediaType' & 'meta' API parameters:

### CLI Microlink API example

```bash
microlink https://blog.alexmaccaw.com/advice-to-my-younger-self&pdf.format=Letter&pdf.margin=1cm&pdf.scale=0.9&mediaType=screen
```

### cURL Microlink API example

```bash
curl -G "https://api.microlink.io" \
  -d "url=https://blog.alexmaccaw.com/advice-to-my-younger-self" \
  -d "pdf.format=Letter" \
  -d "pdf.margin=1cm" \
  -d "pdf.scale=0.9" \
  -d "mediaType=screen" \
  -d "meta=false"
```

### JavaScript Microlink API example

```javascript
import mql from '@microlink/mql'

const { data } = await mql('https://blog.alexmaccaw.com/advice-to-my-younger-self', {
  pdf: {
    format: "Letter",
    margin: "1cm",
    scale: 0.9
  },
  mediaType: "screen",
  meta: false
})
```

### Python Microlink API example

```python
import requests

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

querystring = {
    "url": "https://blog.alexmaccaw.com/advice-to-my-younger-self",
    "pdf.format": "Letter",
    "pdf.margin": "1cm",
    "pdf.scale": "0.9",
    "mediaType": "screen",
    "meta": "false"
}

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://blog.alexmaccaw.com/advice-to-my-younger-self",
  pdf.format: "Letter",
  pdf.margin: "1cm",
  pdf.scale: "0.9",
  mediaType: "screen",
  meta: "false"
}

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://blog.alexmaccaw.com/advice-to-my-younger-self",
    "pdf.format" => "Letter",
    "pdf.margin" => "1cm",
    "pdf.scale" => "0.9",
    "mediaType" => "screen",
    "meta" => "false"
];

$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://blog.alexmaccaw.com/advice-to-my-younger-self")
    q.Set("pdf.format", "Letter")
    q.Set("pdf.margin", "1cm")
    q.Set("pdf.scale", "0.9")
    q.Set("mediaType", "screen")
    q.Set("meta", "false")
    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
import mql from '@microlink/mql'

const { data } = await mql('https://blog.alexmaccaw.com/advice-to-my-younger-self', {

  pdf: {

    format: "Letter",

    margin: "1cm",

    scale: 0.9

  },

  mediaType: "screen",

  meta: false

})
```

When the PDF feels too cramped, too wide, or overly "print-like," adjust layout controls before reaching for custom scripts.

## The PDF is missing content or printed too early

Start with a fast navigation event, then wait for the exact content you need:

The following examples show how to use the Microlink API with CLI, cURL, JavaScript, Python, Ruby, PHP & Golang, targeting 'https://dev.to' URL with 'pdf', 'meta', 'waitUntil' & 'waitForSelector' API parameters:

### CLI Microlink API example

```bash
microlink https://dev.to&pdf&waitUntil=domcontentloaded&waitForSelector=article
```

### cURL Microlink API example

```bash
curl -G "https://api.microlink.io" \
  -d "url=https://dev.to" \
  -d "pdf=true" \
  -d "meta=false" \
  -d "waitUntil=domcontentloaded" \
  -d "waitForSelector=article"
```

### JavaScript Microlink API example

```javascript
import mql from '@microlink/mql'

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

### Python Microlink API example

```python
import requests

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

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

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://dev.to",
  pdf: "true",
  meta: "false",
  waitUntil: "domcontentloaded",
  waitForSelector: "article"
}

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://dev.to",
    "pdf" => "true",
    "meta" => "false",
    "waitUntil" => "domcontentloaded",
    "waitForSelector" => "article"
];

$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://dev.to")
    q.Set("pdf", "true")
    q.Set("meta", "false")
    q.Set("waitUntil", "domcontentloaded")
    q.Set("waitForSelector", "article")
    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
import mql from '@microlink/mql'

const { data } = await mql('https://dev.to', {

  pdf: true,

  meta: false,

  waitUntil: "domcontentloaded",

  waitForSelector: "article"

})
```

This is usually more reliable than waiting a fixed number of seconds.

If the page still needs cleanup:

- Use `click` to open tabs or dismiss UI before printing.
- Use `styles` to hide sticky headers, banners, or controls.
- Use `mediaType: 'screen'` if the print stylesheet removes important content.

## Still stuck

Check the full [error codes reference](https://microlink.io/docs/api/basics/error-codes) or see [common troubleshooting](https://microlink.io/docs/guides/common/troubleshooting) for timeout, auth, and plan errors. If the issue is specific to authenticated targets, return to [private pages](https://microlink.io/docs/guides/pdf/private-pages).

## Back to guides

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

Last updated on April 13, 2026

[Edit on GitHub](https://github.com/microlinkhq/www/blob/master/src/content/docs/guides/pdf/troubleshooting.md)