DEV Community: Dmitry Petrakov

Secure File Upload in Go: 7 Attacks and How We Mitigated Them

Dmitry Petrakov — Tue, 30 Jun 2026 08:15:18 +0000

"Build a PDF upload form" – sounds like a 30-minute task. Claude/GPT will write the handler, we'll add accept=".pdf" on the frontend, multer on the backend – and we've got a working upload. Ship it.

The problem is that a working upload and a secure upload are two very different things. The gap between them is a handful of vulnerabilities, each of which can turn your server into an entry point for an attacker.

With the proliferation of LLM tools, the barrier to entry in software development has dropped dramatically. That's great – more people can build products. But along with the barrier to entry for development, the barrier to entry for vulnerabilities has dropped too. When an LLM generates file upload code, it solves the functional problem: accept a file, save it, process it. Security? "I'll add that later." And "later" usually comes after an incident.

I decided not to wait for an incident and figured it out upfront: what attacks exist around file uploads, what happens when you forget about them, and how we defended against them in a real project.

Disclaimer. This is not a universal security guide, nor a claim that "I know the right way." It's an engineering case study: how I designed upload protection for a specific service and what trade-offs I made. The example is a browser extension for converting PDF to Markdown. A PDF converter by itself might not warrant this level of protection. But the approaches are universal and applicable to systems where the stakes are higher: medical documents, financial reports, legal scans, UGC platforms. I'm demonstrating the principles with real code – and you decide which ones apply to your case.

TL;DR – in this article, I break down 7 attacks on file upload and how I mitigated them in a Go backend:

File type spoofing → magic bytes %PDF, never trust the extension
Disk exhaustion → MaxBytesReader + per-device slot limits
Path Traversal → fixed filename {UUID}/input.pdf, no user input in paths
SSRF → DNS resolution before the request, redirect blocking, private IP denylist
Replay attack → nonce + timestamp + ECDSA signature on every request
Device spoofing → cryptographic identity via WebCrypto (ECDSA P-256)
Application-level abuse → rate limit + signature + slots

Summary table with statuses – at the end of the article.

Upload Architecture: What Happens When You Send a File

Before talking about attacks, let's look at the file's journey through the system:

Two upload channels:

Direct upload – the user selects a file or drags and drops it
URL upload – the user provides a link to a PDF

Each channel carries its own set of threats, and each requires its own defenses.

But before we dig into specific attacks, we need to understand the foundation that our entire security model rests on.

All code snippets below are simplified excerpts from the real project, highlighting the key checks. The actual code may differ in error handling and additional edge cases.

Foundation: Anonymous Device Identity

Why so complex? If your backend uses conventional authentication (JWT, sessions, OAuth) – you can skip this section; your auth layer already solves the identity problem. We describe this approach for a specific case: a product with no logins or accounts, where you still need to control load per-device. If your project includes authentication – use it, it's simpler and more reliable.

In most applications, file upload is protected by login – you have an account, the server knows who you are. Our browser extension has no registration and no accounts. So how do we distinguish a legitimate user from an attacker? How do we rate-limit requests when there's no login?

We solved this through cryptographic device identity – essentially, each browser profile becomes an anonymous yet verifiable "account."

Important: this is not user tracking or covert identity fingerprinting. The device_id is tied to a key pair in the IndexedDB of a specific browser profile. We don't know who the person is – we only know that this same browser profile has made requests before. Incognito window = new device. Extension uninstalled = keys lost forever. At the auth-model level, device_id provides no cryptographic linkage between devices. That said, the server operator still has indirect signals (IP, ASN) that could theoretically be used to hypothesize about device correlation – but that is not part of the auth protocol and is not used for identification.

How It Works

On first launch, the extension generates an ECDSA P-256 key pair via the WebCrypto API:

const keyPair = await crypto.subtle.generateKey(
  { name: 'ECDSA', namedCurve: 'P-256' },
  false,  // extractable = false – the key cannot be exported!
  ['sign', 'verify']
);

The critical detail: extractable: false. The private key is stored in the browser's IndexedDB, but it cannot be extracted – not via JavaScript, not via DevTools, not via extensions. You can only ask the browser to sign data with this key.

The extension then sends the public key to the server (POST /register) and receives a device_id and device_token in response. From this point on, every API request is signed with the private key:

Header	Purpose
`Authorization: Bearer <token>`	Device identification
`X-Timestamp`	Request time (±5 min window)
`X-Nonce`	Unique request ID (anti-replay)
`X-Body-SHA256`	Body hash – data integrity
`X-Signature`	ECDSA signature of all the above

The signature covers: METHOD + PATH + TIMESTAMP + NONCE + BODY_HASH. Forging it without the private key is impossible.

Signature ≠ encryption. An ECDSA signature ensures the integrity and authenticity of a request, but not confidentiality. The file contents, token, and metadata are transmitted in plaintext without TLS. Request signing is a complement to HTTPS, not a replacement.

The server verifies the signature using the public key bound to the device_id. If the signature doesn't match – the request is rejected, regardless of whether the token is valid.

Why This Matters for File Upload

This model gives us something you normally don't get without accounts:

Per-device control – we can limit the number of concurrent tasks, files per day, and requests per minute for each device (i.e., browser profile)
Cost of creating a "new account" – an attacker can't just swap cookies or tokens. They need to generate a new key pair and go through registration, which is limited to 5 attempts per IP per hour
Protection against token theft – even if the device_token leaks, it's useless without the private key (which can't be exported)
Request integrity – the request body (including the file) is covered by the signature via a SHA256 hash. Tampering with the file in transit is impossible

Essentially, each browser profile gets its own unforgeable "passport." And all the limits we'll discuss next – slots, rate limits, size restrictions – work precisely because we can reliably identify the device.

Is this protection absolute? No. A technically motivated attacker could write an emulator that reproduces the entire chain: key generation, registration, request signing – without a browser at all. But that's the whole point of the approach: we significantly raise the barrier to entry. Without cryptographic identity, attacking the API takes a single curl command or a couple of clicks in Postman – fire off request after request, swapping headers. With our model, the attacker needs to implement ECDSA P-256, correctly form the canonical string, sign every request, manage nonces and timestamps – and all of this for a limit of 3 active slots and 5 registrations per hour per IP. The cost of the attack grows by orders of magnitude, while the payoff stays the same.

Attack 1: File Type Spoofing (Malicious File Upload)

The Attack

An attacker renames a malicious file (script, executable, HTML with XSS) to report.pdf and uploads it. If the server trusts the extension – it will save the file, and under certain conditions may execute it or serve it to other users.

How We Defended

Three layers of file type validation:

Layer 1 – Frontend (extension):

const ALLOWED_TYPES = ['application/pdf'];
const ALLOWED_EXTENSIONS = ['.pdf'];

function validateFile(file) {
  const isPdf = ALLOWED_TYPES.includes(file.type) ||
                ALLOWED_EXTENSIONS.some(ext =>
                  file.name.toLowerCase().endsWith(ext));

  if (!isPdf) return { valid: false, error: 'PDF only' };
  // ...
}

We check both the MIME type and the extension. But frontend validation is just a UX filter, not a security measure. Anyone can send a request directly, bypassing the extension.

Layer 2 – Backend, request Content-Type:

The server routes the request by Content-Type: multipart/form-data for files, application/json for URLs. This isn't content validation, but it's the first server-side barrier.

Layer 3 – Backend, magic bytes (file signature):

pdfMagicBytes = "%PDF"

header4 := make([]byte, 4)
_, err = file.Read(header4)
if string(header4) != pdfMagicBytes {
    respondError(w, http.StatusBadRequest,
        models.ErrCodeValidationError,
        "File is not a valid PDF")
}
file.Seek(0, 0) // Reset position for further processing

This is the key check. Every file format starts with a specific byte sequence – "magic bytes." PDF always starts with %PDF. Even if an attacker renames an .exe to .pdf, the first bytes will give it away.

Important: we validate the actual file contents, not what the browser wrote in the header. Headers are easy to forge; bytes are not (unless, of course, the attacker crafted a file that is simultaneously a valid PDF and something malicious – such polyglots do exist, more on that below).

Attack 2: Disk Exhaustion (File Size DoS)

The Attack

An attacker uploads a gigabyte-sized file (or thousands of files in a row) to exhaust the server's disk space or memory.

How We Defended

Three layers of size limits:

The key element – http.MaxBytesReader at the middleware level:

r.Body = http.MaxBytesReader(w, r.Body, h.cfg.Storage.MaxFileSize + 1024*1024)

This function wraps r.Body and stops reading as soon as the limit is exceeded. The server won't read 10 GB just to say "file too large" – it will stop at the 11th megabyte.

And here our device identity model kicks in at full strength. Since each browser profile is cryptographically bound to a device_id, we can limit load per-device:

const maxJobsPerDevice = 3

Three active slots per device (a slot is occupied by tasks in queued, processing, ready, and error statuses – until auto-cleanup or manual deletion). Bypassing this by swapping cookies or tokens is impossible. To get new slots, the attacker needs to create a new browser profile, generate keys, and go through registration (which is limited to 5 attempts per IP per hour).

Attack 3: Path Traversal (Directory Traversal)

The Attack

An attacker sends a file named ../../../etc/passwd or ..\..\windows\system32\config.txt. If the server uses the filename for storage without sanitization, the file ends up not in the uploads folder, but in an arbitrary location on the filesystem.

How We Defended

Frontend – filename sanitization:

function sanitizeFileName(name) {
  return name
    .replace(/[/\\?%*:|"<>]/g, '-')  // Remove dangerous characters
    .replace(/^\.+/, '')              // Remove leading dots
    .replace(/\.+$/, '')              // Remove trailing dots
    .substring(0, 255)                // Limit length
    .trim();
}

But the real defense is on the backend, where the filename is completely ignored:

func (h *JobsHandler) saveFile(jobID uuid.UUID, file io.Reader) error {
    jobDir := filepath.Join(h.cfg.Storage.SharedDataPath, jobID.String())
    os.MkdirAll(jobDir, 0755)

    filePath := filepath.Join(jobDir, "input.pdf") // Fixed filename!
    // ...
}

The file is always saved as {UUID}/input.pdf. No user input in the path whatsoever. The UUID is generated by the server – predicting or guessing it is impossible. This is a robust defense against path traversal at the storage path level.

But the filename doesn't end there. The original filename lives on as metadata: in the database, in the UI, in the Content-Disposition header when downloading results. At the storage path level, the problem is fully closed (the user-provided name is not involved). But at the output level – downloads, UI display – the name needs to be properly escaped to prevent XSS or header injection. In our case, frontend sanitization (removing special characters, limiting length) is the first barrier, while the main responsibility lies in correct escaping when serving the result.

Attack 4: SSRF (Server-Side Request Forgery)

The Attack

When uploading via URL, the attacker submits not a link to a PDF, but an internal service address: http://169.254.169.254/latest/meta-data/ (the metadata endpoint – identical across AWS, GCP, and other cloud providers like Yandex Cloud and VK Cloud), http://localhost:6379/ (Redis), or http://192.168.1.1/admin. The server, trusting the URL, makes the request on its own behalf – and the attacker gains access to internal infrastructure.

SSRF is part of the OWASP Top 10 and is one of the most prevalent vulnerabilities in modern applications.

How We Defended

Step 1 – IP address validation:

The idea is simple: before making an HTTP request to the user-provided URL, we resolve DNS and verify that all resulting IPs are public:

func validatePublicURL(rawURL string) error {
    u, err := url.Parse(rawURL)
    // ... scheme and host validation

    ips, err := net.LookupIP(u.Hostname())

    for _, ip := range ips {
        if isPrivateOrReservedIP(ip) {
            return fmt.Errorf("URL resolves to private/reserved IP")
        }
    }
    return nil
}

func isPrivateOrReservedIP(ip net.IP) bool {
    if ip.IsLoopback() { return true }        // 127.0.0.0/8, ::1
    if ip.IsLinkLocalUnicast() { return true } // 169.254.0.0/16 – cloud metadata
    if ip.IsMulticast() { return true }

    if ip4 := ip.To4(); ip4 != nil {
        // 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
        if ip4[0] == 10 { return true }
        if ip4[0] == 172 && ip4[1] >= 16 && ip4[1] <= 31 { return true }
        if ip4[0] == 192 && ip4[1] == 168 { return true }

        // TODO: 100.64.0.0/10 (Carrier-Grade NAT)
        // TODO: 198.18.0.0/15 (benchmark testing)
        // TODO: 0.0.0.0/8, 192.0.0.0/24, 192.0.2.0/24 (documentation)
        // TODO: 198.51.100.0/24, 203.0.113.0/24 (documentation)
    }

    // IPv6 ULA (fc00::/7)
    if ip[0] == 0xfc || ip[0] == 0xfd { return true }
    // TODO: ::ffff:0:0/96 (IPv4-mapped), 2001:db8::/32 (documentation)
    // TODO: dial-time validation for DNS rebinding protection

    return false
}

Caveat: this is a denylist approach – we enumerate "what to block." OWASP recommends a positive allowlist for SSRF (only allow known-safe destinations). A denylist is simpler to implement but easier to bypass: if we miss a range (e.g., 100.64.0.0/10 – Carrier-Grade NAT or 198.18.0.0/15 – benchmark), the request goes through. For our use case, the denylist covers the main risks, but for critical infrastructure you should move to an allowlist or dial-time validation.

Step 2 – Blocking redirects:

httpClient = &http.Client{
    CheckRedirect: func(req *http.Request, via []*http.Request) error {
        return http.ErrUseLastResponse // Do not follow redirects
    },
}

A classic trick: http://safe-looking-url.com → 302 → http://169.254.169.254/. We don't follow redirects at all. If a URL returns a 3xx response, the request is rejected:

if resp.StatusCode >= 300 && resp.StatusCode < 400 {
    respondError(w, http.StatusBadRequest, ...,
        "URL redirects are not allowed for security reasons")
}

A note on DNS Rebinding: there's a more sophisticated attack where a DNS name first resolves to a public IP (passes validation), then resolves to a private IP (when the HTTP client actually connects). Full DNS rebinding protection requires pinning the resolved address or using a specialized HTTP client. In our case, this vector is partially mitigated by redirect blocking and the single-shot nature of the request.

Attack 5: Replay Attack (Request Reuse)

The Attack

An attacker intercepts a legitimate file upload request and sends it again – repeatedly. The result: dozens of identical tasks, quota exhaustion, server load.

How We Defended

This is where the signature system we described in the "Foundation" section comes into play. Every request already contains a timestamp, nonce, and ECDSA signature – and these are precisely what make a replay attack futile.

Server-side checks:

Time window – requests older than 5 minutes are rejected
Nonce uniqueness – every nonce is stored in Redis with a 5-minute TTL. Duplicate nonce → 409 Replay Detected
Body integrity – the SHA256 hash of the body is compared against the declared value. Tampering with the body while preserving the signature is impossible
Cryptographic signature – the signature covers the method, path, timestamp, nonce, and body hash. Without the private key, creating a valid signature is impossible

// Body integrity check
actualHash := sha256.Sum256(bodyBytes)
if !strings.EqualFold(hex.EncodeToString(actualHash[:]), bodySHA256Header) {
    respondError(w, http.StatusUnauthorized, ..., "Body hash mismatch")
}

This means: even if an attacker intercepts a request, they can't replay it (nonce already used), modify it (signature won't match), or stretch it in time (timestamp expired).

Attack 6: Device Spoofing (Identity Spoofing)

The Attack

An attacker tries to impersonate another device to use its quotas, access its results, or simply bypass rate limits.

How We Defended

As we described in the "Foundation" section, device identity is based on asymmetric cryptography, not simple tokens. This makes spoofing fundamentally impossible:

The private key can't be stolen – extractable: false in the WebCrypto API means that even a malicious extension cannot read the key from IndexedDB. It can only be used for signing
A token without the key is useless – the device_token grants the right to send a request, but without an ECDSA signature from the private key, the server will reject it
Creating a "new device" is expensive – requires a new browser profile + registration, limited to 5 attempts per IP per hour
The key is tied to the browser profile – switching tabs, restarting, updating the extension – the key persists. Only deleting the profile or the extension causes the key to be lost

Attack 7: Mass Abuse via Upload

The Attack

Mass-submitting upload requests to overload the server – saturating the network, disk, or CPU (PDF parsing is resource-intensive). This is not a network-level DDoS (that's handled by CDN, WAF, and infrastructure solutions like Cloudflare, Qrator, DDoS-Guard, etc.), but application-level abuse – exploiting the upload business logic.

How We Mitigate the Risk

Defense in depth at the application layer:

Layer	Mechanism	Limit
Registration	Rate limit on `/register`	5 per hour per IP
Requests	Signature on every request	No key – no access
Concurrency	Per-device slots	3 active slots
Size	MaxBytesReader	11 MB per request
Request body	Multipart part size	10 MB per file

To mass-abuse file uploads, an attacker would need to:

Create many devices (rate-limited registration)
For each device – generate a key pair and sign every request
Each device is limited to 3 active slots and 10 MB per file

This raises the cost of mass abuse at the application level. But it is not a substitute for network-level DDoS mitigation (Cloudflare, Qrator, DDoS-Guard, and similar solutions) – SYN floods or HTTP floods at the infrastructure level are beyond what application-level logic can handle.

On IP-based rate limiting and CGNAT. Yes, we know: thousands of users can sit behind a single mobile carrier IP. That's why the IP limit is not the primary signal, but a supplementary one, and only on the device registration endpoint. Working requests are rate-limited by device_id, not by IP. If normal, legitimate traffic comes from a single mobile IP – it goes through. The limit only kicks in on an anomalous burst of registrations, characteristic of automated farming.

What Else Exists: Attacks Where Protection Is Incomplete

Honesty is the best policy. Here are the vectors we're aware of and where our defenses are still imperfect:

PDF Bomb (Decompression Bomb)

A PDF can contain compressed streams that expand to gigabytes when decompressed. A 5 MB file can become 10 GB during parsing.

What already protects us: the conversion engine (MinerU by default, Docling as an opt-in) runs in a separate Docker container. The compose configuration specifies a memory limit and timeout:

The separate conversion service, 15-minute timeout, and memory limit in the deploy configuration reduce the blast radius: even if a PDF bomb starts decompressing, the consequences are contained within a single container and don't affect the API, the database, or other workers. The exact OOM behavior depends on the runtime environment (Docker Desktop, Swarm, and Kubernetes apply deploy.resources differently), but the isolation principle works in every case.

The timeout is a second line of defense: even if memory doesn't run out but decompression drags on, the worker will forcefully terminate processing and mark the task as failed.

What this doesn't cover: we have no preventive protection – we don't analyze the compression ratio before processing begins. A PDF bomb will still start decompressing, just within an isolated environment. For full protection, you could add an input heuristic: an anomalously high compression ratio (file size vs. number of streams/pages) is a reason to reject the file before processing.

Malicious PDF Content

PDF is a full-fledged container that can contain:

Embedded JavaScript
Forms with auto-submit
Links to external resources
Embedded files of other formats

We don't execute or render PDFs – we only extract text and structure, which substantially reduces the risk. And the engine's container isolation means that even if the parser is vulnerable to a specially crafted PDF, the consequences are confined to the container.

What this doesn't cover: there is no antivirus scanning (ClamAV) and no CDR (Content Disarm & Reconstruct – rebuilding the PDF while stripping potentially dangerous elements: JavaScript, forms, embedded files). For scenarios where the conversion output is served to third parties, both the incoming PDF and the output Markdown should be checked for malicious links/scripts. A separate concern is timely updates to the parsers themselves (MinerU, Docling and their dependencies): a PDF parser is its own attack surface, and CVEs can appear regularly.

Storage and Access to Uploaded Files

It's worth separately noting what the OWASP File Upload Cheat Sheet lists as mandatory items, and what we've already implemented but haven't explicitly discussed:

Files are stored outside the webroot – uploaded PDFs reside in shared storage between the API and worker, not in a publicly accessible directory. Nginx does not serve them directly.
The original PDF is not exposed externally – the uploaded file is not served via Nginx or a separate endpoint. Only the conversion result (Markdown) is available through the API, and the original is deleted after processing.
The application does not execute uploaded files – even if a non-PDF somehow gets uploaded, it won't be interpreted by the server. The upload storage is not used as a public serving directory and is not an execution point.

Polyglot Files

A polyglot is a file that is simultaneously a valid PDF and, for example, a valid ZIP or HTML. Our magic bytes check passes (%PDF at the start), but other software may interpret the file differently.

Current status: only the first 4 bytes are checked. No deeper PDF structure analysis is performed.

Solution: validate the PDF structure (xref table, trailer) or use specialized libraries for deep validation.

DNS Rebinding

As mentioned in the SSRF section – there's a time gap (TOCTOU) between the IP check and the actual HTTP request. An attacker could theoretically bypass validatePublicURL via a controlled DNS server: return a public IP on the first resolve (passes validation), then return a private IP on the second (when the HTTP client establishes the connection).

What already protects us: even with successful DNS rebinding, the attacker only gets blind SSRF – the server can "touch" the internal address, but the response won't be returned. The reason: the response from an internal service (JSON from the cloud metadata API, text from Redis, HTML from an admin panel) won't pass the magic bytes check (%PDF), and the request will be rejected with a generic message "URL does not point to a valid PDF file". No data from the response is returned to the user.

What this doesn't cover: blind SSRF still allows "reaching" internal services with a GET request. For critical infrastructure, this can be undesirable – for example, cloud provider metadata APIs (AWS, GCP, as well as Yandex Cloud, VK Cloud, and others) may return IAM tokens via GET without authorization. Full protection means moving IP validation to the TCP connection level (dial-time validation) to eliminate the TOCTOU gap between DNS resolution and connection establishment.

Summary Table: Attacks and Protection Status

Attack	Severity	Status	How We're Protected
File type spoofing	High	Protected	MIME + extension + magic bytes
Disk exhaustion	High	Protected	MaxBytesReader + multipart limit + slots
Path Traversal	Critical	Protected	Fixed filename `input.pdf` + UUID directories
SSRF	Critical	Risk reduced	IP denylist + redirect blocking (not allowlist, no dial-time validation)
Replay attack	Medium	Protected	Nonce + timestamp + ECDSA signature
Device spoofing	High	Protected	Asymmetric cryptography (P-256)
Application-level abuse	High	Risk reduced	Rate limit + signature + slots (not a substitute for network DDoS mitigation)
PDF bomb	Medium	Partial	Container isolation + OOM + 15 min timeout, no preventive analysis
Malicious PDF	Medium	Partial	No rendering + container isolation, no antivirus
Polyglot files	Low	Partial	Magic bytes only, no deep analysis
DNS Rebinding	Low	Partial	Blind SSRF only – magic bytes block data leakage, no dial-time validation

The Approach Scales

Everything described above was demonstrated using a PDF-to-Markdown converter, but the same set of principles was applied in another UGC project involving image uploads. There, instead of magic bytes %PDF – image.DecodeConfig() in Go (effectively the same magic bytes via the standard library); instead of container isolation against PDF bombs – a pixel limit on input (reject before decoding into memory); and instead of a fixed input.pdf – server-generated UUIDs at every path level. Additionally, re-encoding is in play: every uploaded image is decoded into a pixel buffer and re-encoded – EXIF, GPS, embedded scripts are destroyed, polyglot files are neutralized. The specifics change (PDF vs. images, extension vs. web app), but the foundation is the same.

Principles Worth Taking With You

Security is not "later." If you're using an LLM to generate file upload code – review the result against the checklist from this article. "I'll add validation later" is technical debt that will bite first.
Never trust the frontend. Any client-side validation is UX, not security. accept=".pdf" on <input> filters accidental mistakes, not targeted attacks. All real protection is on the server.
Validate content, not metadata. The file extension and Content-Type are "what the file calls itself." Magic bytes are "what the file actually is."
Don't use user-provided filenames in storage paths. UUID + fixed name closes the storage-path aspect of path traversal. But the filename as metadata (database, UI, Content-Disposition) still needs to be validated and escaped separately.
When uploading by URL, validate the IP before the request. SSRF is an attack you can't filter after the request has already been sent. Resolve DNS, check the ranges, block redirects.
Make the attack economically unattractive. Absolute protection doesn't exist – a motivated attacker will find a way. But you can make the cost of the attack vastly exceed the potential payoff.
Be honest about the gaps. Security is a process, not a state. Knowing your weak spots and planning to close them is better than believing you're invulnerable.

This case study comes from building pdf2md.dev: convert a PDF to clean, LLM-ready Markdown from the web app (no signup, files auto-deleted), or as a REST API and hosted MCP for agents and RAG pipelines. The privacy notice states retention and training policy in plain language.

What actually breaks when you turn PDFs into Markdown

Dmitry Petrakov — Mon, 29 Jun 2026 12:05:08 +0000

"Convert a PDF to Markdown" sounds like a solved problem. Take the text out, turn headings into #, turn tables into pipes, done.

After building a converter for it, I have a less satisfying answer: the easy cases are easy, and the hard cases are not edge cases. They are the documents people actually care about – research papers, annual reports, invoices, scanned contracts, specs, and the table-heavy PDFs someone wants to feed into an LLM.

Disclosure: I build pdf2md.dev, so I have skin in this game. This is not a benchmark claiming "we're the best." It is a breakdown of the failure modes I had to handle and the trade-offs I made – written so it's useful even if you never touch my tool and just want to evaluate your own.

A PDF is not a document

The core problem is that a PDF does not usually contain "a document" the way Markdown, HTML, or DOCX does.

It contains drawing instructions: put these glyphs at these coordinates, draw this line here, place this image there. The structure you see as a reader is reconstructed by your eyes:

that larger bold text is probably a heading
those aligned numbers are probably a table
that block on the left should be read before the block on the right
that superscript belongs to a formula
that scanned page has no text layer at all

A converter has to rebuild all of that from layout, geometry, OCR, and heuristics. If it only "extracts text," it will work on the demo PDF and fall apart on the first real report.

Here are the main things that break, roughly ordered by how often they bite.

1. Tables are not one problem

Simple tables are fine. If the PDF has a clean grid and each cell maps to one row and one column, Markdown is a good target:

| Quarter | Revenue | Growth |
|---------|---------|--------|
| Q1      | $1.2M   | +8%    |
| Q2      | $1.4M   | +17%   |

Renders to:

Quarter	Revenue	Growth
Q1	$1.2M	+8%
Q2	$1.4M	+17%

The trouble starts when the table stops being a simple grid.

Merged cells do not map cleanly to GitHub-flavored Markdown. Nested headers have a hierarchy Markdown tables cannot represent. Rotated tables add a reading-order problem before you even get to cell detection. Borderless tables are worst of all, because the grid exists only as alignment.

This is where converters quietly get dishonest. They return a table that looks tidy but has shifted columns, duplicated headers, or numbers attached to the wrong labels. That is more dangerous than an obvious failure – especially if the output flows into an LLM or a RAG index, where nobody re-reads it.

My rule for this class of problem: preserve as much structure as the target format can honestly express, and don't pretend Markdown can encode everything a PDF table visually implies. Straight grids come out ready to use. Complex financial or scientific tables may still need a visual check. That is less magical, but it is the difference between saving time and silently corrupting data.

2. Reading order is layout analysis, not text extraction

Academic papers, magazines, datasheets, and many reports use two or three columns. A naive extractor reads across the page by x/y position and produces nonsense:

First line of column one first line of column two
second line of column one second line of column two

The right behavior is to detect column boundaries, read each column top-to-bottom, then move on. That requires layout analysis – the text stream alone is not enough.

The same problem hits sidebars, captions, footnotes, running headers, and page numbers. A human ignores a repeated header automatically; a converter has to decide whether those fragments are content, metadata, or noise. Get it wrong and you don't just produce ugly Markdown – you change the meaning.

3. Formulas are reconstructed, not copied

Mathematical notation is a layout problem too. In a PDF, a formula is a set of glyphs placed carefully on the page: ∑, √, superscripts, subscripts, fraction bars, Greek letters, spacing. Turning that back into something usable means producing LaTeX-like text:

$$
\sum_{i=1}^{n} x_i
$$

Renders to:

If the converter only sees characters in approximate order, an equation becomes a line of floating symbols – useless for documentation, search, or LLM context. This is why I don't trust regex-only PDF pipelines for technical documents. They're fine for plain text; formulas need the converter to understand visual structure.

4. Scanned PDFs change the entire pipeline

A scanned PDF may have no embedded text at all – it's just images of pages. Now the problem is OCR, with its own failure modes:

scan quality dominates everything
skewed or low-contrast pages hurt recognition
tiny text and dense tables are slow
handwriting is not reliably recognized
OCR produces plausible-looking mistakes, which are the worst kind

For printed or typeset text, good scans convert well. A sharp 300 DPI page with high contrast is a completely different input from a crooked phone photo of a faded fax.

There's also a product decision every converter has to make: what happens when a long scan exceeds the processing budget? Failing the whole job is simple to implement and a terrible experience. The behavior I chose is to return the Markdown produced within the budget and mark the job as truncated – a partial result with an explicit signal, instead of losing everything. The signal is the important part. A partial result without a truncation marker is just another form of silent data loss.

5. Images are either content or noise

Images in PDFs are ambiguous. Sometimes they're essential – diagrams, charts, stamps, signatures. Sometimes they're decorative backgrounds. Sometimes the whole page is an image but the user wants text, not embedded base64.

So "include images" is not one setting. The practical version is three different intents:

embed images when the Markdown should be self-contained
use placeholders when the user wants clean text output
run OCR on scanned pages when text needs to be recovered

There is no universal best choice. A Markdown file headed for a knowledge base, an LLM prompt, or a legal archive each wants different output.

6. The converter itself can fail before the Markdown does

The visible part of a converter is the Markdown. The part that decides whether you can trust it is job reliability, and those failures are boring:

a conversion hangs forever
a heavy OCR job runs out of memory
a worker dies halfway through
a job gets retried too aggressively
one large file blocks everyone else
the user closes the tab before the result is ready

This is where a weekend script and a service diverge. My implementation ended up with a real job lifecycle:

The system tracks each job, retries bounded failures, applies time budgets, deletes input files after processing, and keeps results only for a short retention window. Those limits are not glamorous, but they are part of trust. A converter that accepts anything, promises instant results, and never explains retention isn't more user-friendly – it's just hiding the operational reality.

Why two engines instead of one

There is no single engine that wins on every document, so I run two.

MinerU is the default. It holds up better on dense documents, heavy OCR, Cyrillic content, and table-heavy scans, and it's the safer choice under memory pressure. Docling is an opt-in: faster and cleaner on simple, well-structured text PDFs, but less forgiving on heavy full-OCR workloads.

So the question isn't "which engine is best?" – it's "which engine is best for this document?" That's an unsatisfying marketing answer and a useful engineering one.

How I'd evaluate any PDF-to-Markdown tool

If you're picking a converter, mine or anyone's, don't start with the landing page. Test it with documents that expose different failure modes:

a simple text PDF with headings and lists
a two-column paper with footnotes
a table with merged headers
a scanned invoice or contract
a technical paper with formulas
a document with screenshots or diagrams
a long PDF that might hit a time budget

As you read the output, the useful questions split in two. First, did the structure survive: does the reading order match the original, are the tables actually correct rather than merely tidy, do the formulas come back usable, and does the OCR admit when it can't read handwriting instead of inventing words? Check for the truncation marker too, because a partial result that isn't labelled as partial is a quiet failure.

The second group is the one people skip, and it's the one that matters most: can you find the file-size limit, the retention window and the privacy policy without digging, can you delete a job yourself, and does the tool explain its limits instead of hiding them? PDF conversion usually touches private documents, so a converter has to earn trust before output quality even comes up.

Privacy, in plain language

Here's the model I wanted, stated the way I think every converter should state it:

you can convert without creating an account
uploaded PDFs are deleted after processing
results are kept only for a short download window, then removed automatically
you can delete a job manually
documents are never used to train models
documents are not sold or used for advertising

The full privacy notice spells it out, and the developer docs cover the API and a hosted MCP endpoint for agent workflows. I'm putting this in the article because retention and training policy are product features when you're asking people to upload contracts and reports, not fine print to bury three clicks deep.

Try your worst PDF

The best test isn't a clean sample document. It's the PDF that already broke your previous workflow – a dense financial table, a two-column paper full of formulas, a long scanned report, something you want to feed into an LLM without losing structure.

Throw it at the web app and see how far the honest 90% gets you. No signup, files auto-deleted.

If it works, great. If it breaks, I genuinely want to know which document exposed the failure – drop the kind of PDF you're fighting in the comments. The last 20% of this problem isn't one bug; it's a long list of document-specific edge cases, and real examples are how converters get better.

Written from first-hand work on the project; I used an AI assistant to tighten the structure, not to invent the technical claims.