Frequently Asked Questions

General Questions

Font Handling

PDF Creation

Text Extraction

PDF Rendering

General Questions

I am getting the below Log4J warning message, how do I remove it?

log4j:WARN No appenders could be found for logger (org.apache.pdfbox.util.ResourceLoader).
log4j:WARN Please initialize the log4j system properly.

This message means that you need to configure the log4j logging system. See the log4j documentation for more information.

PDFBox comes with a sample log4j configuration file. To use it you set a system property like this

java -Dlog4j.configuration=log4j.xml org.apache.pdfbox.ExtractText <PDF-file> <output-text-file>

If this is not working for you then you may have to specify the log4j config file using a URL path, like this:

log4j.configuration=file:///<path to config file>

Is PDFBox thread safe?

PDFBox has experimental support for read-only operations on the same PDDocument from different threads.

For all other uses cases only one thread may access a single document at a time. You can have multiple threads each accessing their own PDDocument object.

Why do I get a “Warning: You did not close the PDF Document”?

You need to call close() on the PDDocument inside the finally block, if you don’t then the document will not be closed properly. Also, you must close all PDDocument objects that get created. The following code creates two PDDocument objects; one from the “new PDDocument()” and the second by the load method.

PDDocument doc = new PDDocument();
try
{
   doc = PDDocument.load( "my.pdf" );
}
finally
{
   if( doc != null )
   {
      doc.close();
   }
}

Font Handling

I’m getting java.lang.IllegalArgumentException: … is not available in this font’s encoding: WinAnsiEncoding

Check whether the character is available in WinAnsiEncoding by looking at the PDF Specification Appendix D. If not, but if it is available in this font (in windows, have a look with charmap.exe), then load the font with PDType0Font.load(), see also in the EmbeddedFonts.java example in the source code download.

PDF Creation

I’m creating a PDF but my page is empty. Why?

Make sure that you closed your content stream before saving.

Text Extraction

Why does the extracted text appear in the wrong sequence?

By default, text extraction is done in the same sequence as the text in the PDF page content stream. PDF is a graphic format, not a text format, and unlike HTML, it has no requirements that text one on page be rendered in a certain order. The order is the one that was determined by the software that created the PDF. To get text sorted from left to right and top to botton, use setSortByPosition(true).

How come I am not getting any text from the PDF document?

Text extraction from a pdf document is a complicated task and there are many factors involved that effect the possibility and accuracy of text extraction. It would be helpful to the PDFBox team if you could try a couple things.

  • Open the PDF in Acrobat and try to extract text from there. If Acrobat can extract text then PDFBox should be able to as well and it is a bug if it cannot. If Acrobat cannot extract text then PDFBox ‘probably’ cannot either.
  • It might really be an image instead of text. Some PDF documents are just images that have been scanned in. You can tell by using the selection tool in Acrobat, if you can’t select any text then it is probably an image.

How come I am getting gibberish(G38G43G36G51G5) when extracting text?

This is because the characters in a PDF document can use a custom encoding instead of unicode or ASCII. When you see gibberish text then it probably means that a meaningless internal encoding is being used. The only way to access the text is to use OCR. This may be a future enhancement.

What does “java.io.IOException: Can’t handle font width” mean?

This probably means that the “Resources” directory is not in your classpath. The Resources directory is included in the PDFBox jar so this is only a problem if you are building PDFBox yourself and not using the binary.

Why do I get “You do not have permission to extract text” on some documents?

PDF documents have certain security permissions that can be applied to them and two passwords associated with them, a user password and a master password. If the “cannot extract text” permission bit is set then you need to decrypt the document with the master password in order to extract the text.

Can’t we just extract the text without parsing the whole document or extract text as it is parsed?

Not really, for a couple reasons.

  • If the document is encrypted then you need to parse at least until the encryption dictionary before you can decrypt.
  • Sometimes the PDFont contains vital information needed for text extraction.
  • Text on a page does not have to be drawn in reading order. For example: if the page said “Hello World”, the pdf could have been written such that “World” gets drawn and then the cursor moves to the left and the word “Hello” is drawn.

PDF rendering

A drop shadow is missing or at the wrong position when rendering a page

Please attach your file in the PDFBOX-3000 issue.

Why are some texts in poor quality and not antialiased?

This is because in some PDFs (e.g. the one in PDFBOX-2814 https://issues.apache.org/jira/browse/PDFBOX-2814), text is not rendered directly, but as a shaped clipping from a background. Java graphics does not support “soft clipping” https://bugs.openjdk.java.net/browse/JDK-4212743, and because of that, the edges are not looking smooth. Soft clipping could be achieved with some extra steps https://community.oracle.com/blogs/campbell/2006/07/19/java-2d-trickery-soft-clipping, but these would cost additional time and memory space. You can have a higher quality by rendering at a higher dpi and then downscale the image.