Move the option before the input document and output filename. wkhtmltopdf parses global options in a separate area from document objects. A command such as wkhtmltopdf input.html output.pdf --page-size Letter can therefore fail, while wkhtmltopdf --page-size Letter input.html output.pdf follows the documented syntax. The message is primarily an argument-order and option-scope error—not evidence of a PDF permission, font, or page-layout failure.
What the error means
wkhtmltopdf’s usage form is wkhtmltopdf [GLOBAL OPTION]... [OBJECT]... <output file>. The project documentation states that options in the Global Options section can only be placed in the global-options area. In practical terms, wkhtmltopdf first reads global switches, then one or more page or table objects, and finally the output file. A global switch encountered after an input object may be rejected with “specified in incorrect location.”
The option named in the message can be --page-size, --margin-left, or another switch. The wording identifies a parser or scope problem; it does not, by itself, identify a broken HTML document or a rendering defect.
The immediate fix: put global options first
- Place every global option immediately after
wkhtmltopdf. - Put the input HTML (or URL) after those options.
- Put the output PDF path last.
wkhtmltopdf --page-size letter --dpi 150 --margin-top 0.2in --margin-bottom 0.2in --margin-left 0.2in --margin-right 0.2in input.html output.pdfThis ordering is the smallest change that matches the documented command shape. A Stack Overflow report against wkhtmltopdf 0.12.0 final described the same failure after options were placed after input.html and output.pdf; moving the switches before those arguments was reported to work. That is a reproduction example, not a guarantee that every command or binary behaves identically.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
- Convert your PDF files into Word, Excel & Co. the easy way
- Convert scanned documents thanks to our new 2022 OCR technology
- Adjustable conversion settings
- No subscription! Lifetime license!
- Compatible with Windows 11, 10, 8.1, 7 - Internet connection required
Incorrect and corrected forms
| Invocation | Why it fails or works |
|---|---|
wkhtmltopdf input.html output.pdf --page-size Letter |
--page-size appears after the object and output, outside the global area. |
wkhtmltopdf --page-size Letter input.html output.pdf |
The global option is parsed before the page object. |
wkhtmltopdf --margin-left 18mm input.html output.pdf |
The margin switch is also in the global area, before the object. |
Global options versus page-object options
Not every switch has the same scope. Global options apply to the conversion as a whole; page-object options belong with a particular page object. The installed binary’s help text is the authority for the version you are actually running.
| Argument category | Placement | Examples |
|---|---|---|
| Global options | After wkhtmltopdf, before any input object |
--page-size, --dpi, margins |
| Page or object options | In the option area for the relevant page object, as accepted by that binary | Options documented as page-specific in --help or --extended-help |
| Objects | Input URL or file, optionally with its object options | input.html, a URL, or multiple page objects |
| Output | Last positional argument | output.pdf |
If you are unsure which category a switch belongs to, do not infer from its name. Run the executable’s help and check the section in which the option is listed. The project usage text specifically identifies --extended-help for details on less common switches.
A repeatable diagnostic procedure
1. Record the executable and version
wkhtmltopdf --versionSave the complete output, including whether the binary reports patched Qt. The official usage text names wkhtmltopdf 0.12.6 (with patched Qt), but deployments vary. Package managers, container images, and vendor bundles can provide different builds, so syntax should be checked against the installed executable rather than assumed from a web example.
2. Reduce the command to a minimal case
wkhtmltopdf --page-size A4 input.html test.pdfIf this succeeds, add your margins, headers, cookies, JavaScript flags, and other switches one at a time. The first addition that reproduces the error narrows the scope or ordering problem.
3. Inspect the exact argument sequence
Copy the command exactly as executed, not the configuration you intended to generate. Look for an input URL or file appearing before a supposed global option, an output filename inserted too early, or an option duplicated in two scopes.
Rank #2
![Doxillion Free Document Converter – Converts DOCX, DOC, PDF, WPS and Many More Files Quickly [Download]](https://m.media-amazon.com/images/I/81tjL48MwxL.png._SL160_.png)
- Convert over 50 document file formats.
- Preview your files from Doxillion before converting them.
- Use batch conversion to convert thousands of files at once.
- Enjoy an easy-to-use, intuitive interface with a Drag and Drop file option.
- Burn your converted or original files directly to disc.
4. Verify argument boundaries and quoting
A path containing spaces must be one argument. Prefer an argument array supplied directly to the process API instead of assembling a shell string. For example, the conceptual array should contain separate entries for --margin-left, 0.2in, input.html, and output.pdf; a wrapper must not concatenate them into one malformed token.
5. Check support in this binary
wkhtmltopdf --extended-helpConfirm that the switch exists, note its documented scope, and check spelling and value syntax. An option copied from another converter or from a different wkhtmltopdf build may be unsupported.
When pdfkit or another wrapper is involved
A hand-typed command can work while a programmatic conversion fails because the wrapper emits a different sequence. Log the final executable path and the complete argument array immediately before spawning wkhtmltopdf. Do not log secrets such as authorization headers or private cookies.
Typical wrapper mistakes
- Appending options after the input and output because a configuration serializer writes positional arguments first.
- Passing a list of options as one string instead of separate arguments.
- Using a configuration key whose spelling does not map to the installed binary.
- Adding an output path in the wrapper and then appending another output path.
- Relying on shell quoting while invoking a process API that does not run a shell.
An issue reported for python-pdfkit with wkhtmltopdf 0.12.4 (patched Qt) shows --margin-left specified in incorrect location alongside several options. That report does not establish a verified pdfkit workaround. Treat it as a reason to inspect the generated invocation, then correct the wrapper’s configuration or construction.
Safe construction pattern
args = [
"--page-size", "Letter",
"--margin-left", "0.2in",
"--margin-right", "0.2in",
"input.html",
"output.pdf"
]
# Pass args directly to the process runner; do not join into one shell string.The syntax above is language-neutral pseudocode: adapt it to your process library while preserving one argument per array element and the same ordering.
Rank #3
- EDIT text, images & designs in PDF documents. ORGANIZE PDFs. Convert PDFs to Word, Excel & ePub.
- READ and Comment PDFs – Intuitive reading modes & document commenting and mark up.
- CREATE, COMBINE, SCAN and COMPRESS PDFs
- FILL forms & Digitally Sign PDFs. PROTECT and Encrypt PDFs
- 1 Year License for 1 Windows & 2 Mobile (Android and/or iOS) devices.
Troubleshooting branches
The error still names the same option
- Print the final command after all wrapper substitutions; the option may still be appended later.
- Search for a second occurrence of the option in defaults, per-page settings, and command-line overrides.
- Run the minimal command directly. If direct execution works, the wrapper—not the HTML—is changing the sequence.
The option is rejected even before an input file
- Check spelling and capitalization against
wkhtmltopdf --help. - Check whether the installed package is a different build or an unusually old version.
- Verify that the value is a separate argument and uses an accepted unit such as
mmorinwhere required.
The parser error disappears but the PDF is wrong
That is a separate rendering problem. First preserve the now-valid argument order, then investigate CSS, missing assets, JavaScript timing, fonts, page breaks, and URL access. Do not move options back to “fix” visual output; parser placement and layout behavior are different issues.
Multiple input pages are involved
Keep global switches before the first object. For object-specific switches, consult the installed help and associate each option with the intended page object. Keep the final output path last. Test with two simple local HTML files before adding remote URLs or complex per-page settings.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Version and maintenance considerations
wkhtmltopdf’s upstream GitHub repository has been archived and read-only since January 2, 2023. That does not change the parser rule, but it does mean that provenance and support expectations matter: record how your package was installed, which build is deployed, and what its help output says. A container or operating-system package may not match a binary downloaded elsewhere.
For reproducible builds, pin the package or container image, capture wkhtmltopdf --version in diagnostics, and keep a minimal conversion test in continuous integration. Test both local files and the URL types your application actually uses.
Or skip the browser setup
If your real goal is a reliable website image or PDF rather than maintaining a wkhtmltopdf process, ScreenshotNeo provides a website screenshot API and MCP server. It accepts a URL and returns PNG, JPEG, WebP, or PDF. Before capture it accepts consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status.
One GET request is enough:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for all parameters. Equivalent Python:
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsRank #4
- Perfect Adobe Acrobat Pro alternative – lifetime license for Windows 10 and 11.
- EDIT text, images, pages, hyperlinks, designs in PDF documents. ORGANIZE PDFs.
- READ and Comment on PDFs – Intuitive reading modes & document commenting and mark up tools!
- CREATE, COMBINE, SCAN and COMPRESS PDFs.
- FILL forms & Digitally Sign PDFs. Work with Digital certificates
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));It also offers full-page captures with lazy images loaded, CSS-selector element capture, dark mode, 12 device presets and custom viewports, retina scale, PDF paper and page-range controls, custom CSS and JavaScript, clicks, selector or network-idle waits, request/resource blocking, custom headers and cookies, timezone and geolocation, transparent backgrounds, resizing, chosen-TTL caching, signed image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API, OpenAPI, and compatibility with parameter names used by other screenshot APIs. An MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.
The Free plan includes 1,000 shots per month with no card. Paid plans start at $5 for 3,000 shots; yearly billing gives two months free, and every feature is included on every plan. Create a free ScreenshotNeo account.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.FAQ
Is “incorrect location” caused by a bad HTML file?
Usually no. The message is emitted while wkhtmltopdf parses command-line arguments, before HTML rendering is the relevant concern.
Can I put every option at the beginning?
Global options belong there. For page-object options, follow the scope shown by the help output for your installed binary, especially when converting multiple objects.
Why does a command copied from a colleague fail on my machine?
Different binaries, package builds, wrapper versions, or argument construction can change accepted options and placement. Compare version output, help text, and the actual argument array.
Best Value
![Doxillion Free Document Converter for Mac – Converts DOCX, DOC, PDF, WPS and Many More Files Quickly [Download]](https://m.media-amazon.com/images/I/51Xjwhv3w2L._SL160_.jpg)
- Convert over 50 document file formats.
- Preview your files from Doxillion before converting them.
- Use batch conversion to convert thousands of files at once.
- Enjoy an easy-to-use, intuitive interface with a Drag and Drop file option.
- Burn your converted or original files directly to disc.
Frequently Asked Questions
Is “incorrect location” caused by a bad HTML file?
Usually no. The message is emitted while wkhtmltopdf parses command-line arguments, before HTML rendering is the relevant concern.
Can I put every option at the beginning?
Global options belong there. For page-object options, follow the scope shown by the help output for your installed binary, especially when converting multiple objects.
Why does a command copied from a colleague fail on my machine?
Different binaries, package builds, wrapper versions, or argument construction can change accepted options and placement. Compare version output, help text, and the actual argument array.
Free tools Windows power users keep installed
One-click scans. No signup required.
The Bottom Line
Put global switches such as --page-size and margins before every input object, verify the installed binary’s help, and inspect the exact argument array produced by wrappers such as pdfkit.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
