Skip to content
Craft Wiki

Troubleshooting

PdfCraft draws with your graphics card, through DirectX 12 by default. If that fails while it starts, PdfCraft tries again with OpenGL by itself. If the window still doesn’t open, start it with Vulkan instead. In PowerShell, from the folder that contains pdfcraft.exe:

Terminal window
$env:WGPU_BACKEND = "vulkan"
& .\pdfcraft.exe
Remove-Item Env:WGPU_BACKEND # go back to the default for later launches

To skip straight to OpenGL, set PDFCRAFT_RENDERER to "gl" in the same way. If neither works, the log has both errors: attach it to a bug report.

On very large windows, or a window stretched across monitors at different scales, PdfCraft may draw below the window’s full size so it doesn’t crash. Make the window smaller, or keep it on one monitor.

The .deb and .rpm install what PdfCraft needs. With the tarball, your system must have the window and graphics libraries it loads at start-up: X11 and Wayland client libraries, libxkbcommon, and a Vulkan driver or Mesa’s OpenGL drivers. Install them with your package manager, then try again. Start PdfCraft from a terminal to see the error.

Open and Save dialogs don’t appear on Linux

Section titled “Open and Save dialogs don’t appear on Linux”

PdfCraft’s file dialogs go through xdg-desktop-portal. Install it with xdg-desktop-portal-gtk or xdg-desktop-portal-kde.

PdfCraft prints through CUPS’s command-line tools. Install cups-client (Debian, Ubuntu) or your distribution’s CUPS client package. Until then, the Print dialog can still save to a PDF.

The Flatpak build can’t reach CUPS, so it lists no printers (#1905). Choose Save as PDF and print the file from another program.

Make sure the printer is installed and the print spooler is running (CUPS on Linux), then open File › Print… again. You can always choose Save as PDF and print the file from another program.

The document’s security settings don’t allow printing. If you know the permissions password, choose File › Protect › Enter permissions password…. File › Protect › Security properties… shows what the document allows.

The printer leaves out text, shading or transparency

Section titled “The printer leaves out text, shading or transparency”

On the Print screen, open Advanced and turn on Print as image, at 300 or 600 dpi. Each page is sent as a picture, which some printers handle better (#4932). The printout won’t have searchable text.

Fit leaves a small margin, so it prints slightly smaller than 100%. Choose Actual size, or press Match page at 100%. If it’s still wrong, check the printer’s own settings with Properties….

These aren’t fixed yet:

  • On Windows, the printer list can stay on Looking for printers… (#5020).
  • Some Windows drivers, such as TOSHIBA Universal PS3 and PaperCut Mobility Print, fail with “Failed to parse print capabilities” (#2430, #6407).
  • On a small or scaled screen, the Print screen can run past the edges (#4455, #5317).

Open PdfCraft again. While it runs, it saves a copy of every document with unsaved changes once a minute. After a crash, the next start offers to recover those copies. Choose Recover, then save them. Copies of password-protected documents stay encrypted, and ask for the password when you recover them.

PdfCraft is in alpha, and editing the existing text of a PDF is one of its weakest areas, especially on complex layouts and in right-to-left and Chinese, Japanese or Korean text. If a PDF is a scan, there is no text to edit until you recognize it with Scan & OCR. To add text on top of a page instead, use Edit a PDF › Text or Fill & Sign › Add text.

If a PDF is secured, a notice above the page says so: its security settings limit what you can change. Choose File › Protect › Enter permissions password… if you know the password. File › Protect › Security properties… shows what the document allows.

Saving: the file shows old content or won’t save

Section titled “Saving: the file shows old content or won’t save”
  • If another program changes the file while it’s open in PdfCraft, turn on Reload documents when their files change on disk in Edit › Preferences….
  • Ctrl+Shift+S saves a copy under another name, which keeps the original as it was.
  • Unsaved changes are copied every minute. See PdfCraft closed and I lost my work.

If a page stays blank or blurry, or shows wrong or overlapping characters, report it. Attach the log and, if you can share it, the PDF. Say which page and what you see.

  • A white window that then closes, on some PCs (#6500).
  • A page made of one very large scanned image may not display (#6494).
  • Some scanned pages look blurred in PdfCraft but not in other readers (#6499).
  • Some PDFs show incorrect or overlapping characters (#6340, #6330).
  • Two-page view of an Arabic PDF runs left to right instead of right to left (#2339).
  • Some files that other tools rewrote can’t be saved with Save As (#6401).
  • After a file is replaced on disk, PdfCraft can still show the old version (#6484).

PdfCraft writes a log you can attach to a bug report. It records crashes, failed autosaves, pages it couldn’t draw, and which graphics renderer it used.

System Log folder
Windows %APPDATA%\PdfCraft\data\logs\
macOS ~/Library/Application Support/PdfCraft/logs/
Linux, FreeBSD ~/.local/share/pdfcraft/logs/
Windows portable zip PdfCraftData\logs\, next to pdfcraft.exe

The current log is pdfcraft.log. The log from the run before is pdfcraft.1.log, so if PdfCraft crashed, attach that one too. The log never records passwords.

On Linux and FreeBSD, PdfCraft’s settings are in ~/.config/pdfcraft/.