[Tex/LaTex] Troubleshooting for biber

biberbiblatexerrors

I'm trying to switch from BibTeX to biber and ran into the problem that biber does not produce any output file. I noticed several questions about problems with biber e.g.,

Biblatex/biber does not work

Biblatex/biber fails with a strange error about missing recode_data.xml file,

Error message when using biber

Major problem with biblatex/biber

Biber not producing any output file

But none of them helped me in my particular situation (which was actually just an old version of biber somewhere in the path of my OS). Since I also noticed that several questions regarding problems with biber were closed as too localized since the underlying problem was due to formatting of a bib resource or similar simple issues, I would rather like to ask for a general troubleshooting guideline for using biber (since I saw many hints like "check/delete the cache", "check versions of this and that" etc.).

What steps are to be taken and what things (in particular files) to be checked if biber does not produce an output file (and its output on the command line does not directly give you the advice what to do)?

Best Answer

This answer can only be fully appreciated with a basic understanding of what biblatex is, how it should be used and the role Biber plays. biblatex in a nutshell (for beginners), bibtex vs. biber and biblatex vs. natbib, Question mark or bold citation key instead of citation number are three very good resources to get started and get a feeling what all of this is about.

If you want to investigate the troubles you are having with Biber, a working knowledge of the basics of your system's command line interface (Terminal, Command Prompt, ...) can be of great help. It is always worth a try to compile a document from the command line and not from an editor to make sure that the editor does not interfere.

Since Biber and biblatex are integrated so closely it is not always entirely clear if the problem you are facing is a Biber problem or a biblatex problem.

There are at least five primary sources of trouble when using Biber

  1. Installation issues
  2. Usage issues
  3. Version mismatches
  4. Cache issues
  5. Malformed .bib files

While the first four can be identified, dealt with and checked quite quickly (and with a simple recipe), the last point has an infinite number of realisations and solutions. You will also note that in the last point it is less clear whether you are actually having trouble with Biber, or if you are having trouble with biblatex or even your .bib file.

Before you start

Before you do anything else, save your important files, make a back-up, work only on a copy of your important files. Delete all temporary files (.aux, .bbl, .bcf, .bgl, ...) or even better start in a new, clean folder. Try to work with an example that is as compact, small and short as possible. Try to get rid of anything that doesn't interfere with the bibliography.

Is Biber Installed Properly?

The first thing to check is if Biber is installed properly. Just open the command line/terminal and type

biber --help

if you get Biber's help page we can be sure Biber is actually installed and your system can find it.

If you don't get the expected output but a message that the command cannot be found, you either don't have Biber installed at all, or for some reason Biber is not installed in a directory in your path.

In MikTeX and TeX live it should be enough to install Biber via the MikTeX Console (on older systems you would use the Package Manager) or tlmgr respectively. The necessary configuration should then be done for you automatically. Remove all manual installations of Biber and let your distribution do its thing.

Make sure that you only have one version of Biber installed, or if you know what you are doing that only the correct version (for more on that see below) is found by your OS. You can find which Biber is found by our OS by typing which biber (on Unix-like systems) or where biber (on Windows Server 2003 or later).

Only try to install Biber manually if it is absolutely necessary and you know what you are doing.

Do You Run Biber (Correctly)?

If you try to compile a document with bibliography, you need to run Biber on your file. Please see Question mark instead of citation number for a thorough explanation of what you need to do and why you need to do that.

The gist of the answer there is that your document called test.tex needs to be compiled with at least

pdflatex test
biber test
pdflatex test

Note that the calls above do not include the file extension, a correct call for Biber is either

biber test

or 

biber test.bcf

In particular the call to Biber is independent of the name of your .bib file (you do not run Biber on your .bib file). You do not call Biber on the .aux file. Both forms biber test and biber test.bcf end up running on the .bcf file, I prefer biber test, but that might be a matter of taste.

In any way, running Biber only makes sense after a successful (pdf/Xe/Lua)LaTeX run, because the .bcf file, through which biblatex and Biber communicate, needs to be created.

ERROR - Cannot find control file 'test.bcf'! - did you pass the "backend=biber" option to BibLaTeX?

or

ERROR - Cannot find control file 'test.bcf'!

means that Biber can not find the .bcf file. There are several possible causes for that message.

  • You forgot to run LaTeX on your document and no .bcf file was created.
  • There were errors early on when you compiled your .tex file so that the .bcf could not be written.
  • You ran Biber on the .bib file and not on the base name of your .tex file.
  • You moved the .bcf to a different location or deleted it using a build or clean-up script or your editor options to 'use a "build" folder'. (Here, it might be worth a try to compile with the bare pdlfatex test, biber test, pdflatex test sequence from the command line to make sure no clean-up scripts and editor shenanigans are involved.)

In particular you do not run Biber on the .aux file, which is what you do with BibTeX.

If you get a message such as 

This is BibTeX, Version 0.99d (MiKTeX 2.9)
The top-level auxiliary file: <filename>.aux
I found no \citation commands---while reading file <filename>.aux
I found no \bibdata command---while reading file <filename>.aux
I found no \bibstyle command---while reading file <filename>.aux

you are running BibTeX on your file while you should actually be running Biber.

Is Your Editor Set Up to Use Biber?

If you use an editor to compile your files for you you might simply have a bibliography button, or a "do all the compilation steps for me" button. You might have to tell your editor to use Biber instead of BibTeX. Please refer to Biblatex with Biber: Configuring my editor to avoid undefined citations for thorough guidelines.

Check the .blg file

If Biber was run on your document, you should be able to find a .blg file in the directory, that file is Biber's log file. On Windows systems a .blg file extension is often classified as 'Performance Monitor' file, you may have to enable displaying of file extension to find the file (https://superuser.com/q/494312). The .blg created by BibTeX or Biber, however, is a reasonably short plain text file that you can open with your favourite text editor. The messages in the .blg file should be able to give you an idea if something went wrong. Have a look at the warnings and errors listed there.

Make Sure Versions of Biber and biblatex Match

When you run Biber you might find the following warning in the console output and .blg file

WARN - Warning: Found biblatex control file version 2.7, expected version 2.9

This tells you that the versions of Biber and biblatex you are using do not match. In actual fact it tells you that the version of the .bcf produced by biblatex does not agree with the version expected by Biber. Note that the control file version does not necessarily agree with either your version of biblatex or Biber. The current version of biblatex for example is 3.10, Biber is on 2.10 and the biblatex control file version is 3.4.

The biblatex control file (this refers to the .bcf from above) is the medium biblatex and Biber use to communicate (it is in fact a bit one-sided: biblatex tells Biber what to do), if the actual format and the format expected by Biber do not agree, some commands might not be understood.

Starting with version 2.5 of Biber (the corresponding biblatex version is 3.4) version mismatches are errors and abort a Biber run. The error message is more prominent and informs you more clearly about what is going on. This can mean that you need to clear auxiliary files after an update of Biber and biblatex.

Please refer to the biblatex manual or the Biber documentation for the compatibility matrix of matching versions.

If you have installed biblatex and Biber via your distribution's package manager, all you need is to run an update. ((sudo)tlmgr update --self --all for TeX live and 'MikTeX Update' and 'MikTeX Update (Admin)' for MikTeX, you may have to run both the Admin and user version twice until all packages are updated, see How do I update my TeX distribution?, How should one maintain and update a MiKTeX installation?, https://miktex.org/howto/update-miktex.)

Cache issues

The Infamous Cache Bug

Prior to version 2.2 a library used by Biber had a bug that could lead to strange error messages along the lines of

Error loading data source package ...

or 

read_file '...' sysopen: no such file or directory '....pm' line ...

or 

recode_data.xml not found in .

The problem was that the cache Biber created and used got corrupted and caused all kinds of weird messages.

The solution was to delete the cache as explained in Biblatex/biber fails with a strange error about missing recode_data.xml file.

If your version of Biber (as displayed by biber --version) is greater than 2.2 you should not have this problem. If it is older consider updating so you don't suffer from this problem any more (if you do update, make sure to update biblatex as well, see the point above).

Corrupted Cache

Occasionally however, Biber's cache can still get corrupted in newer versions of Biber. See for example Biber 2.14 - Puzzling repeated error : "Invalid format '2020-01-01' of date field 'date' - ignoring" and Very strange error suddenly appeared running Biber. It's not quite clear to me why that happens. The cache usually lives in a temporary folder, maybe over-eager clean-up tools remove some files. Maybe an anti-virus software removed some files or blocks access to parts of the cache.

In those cases Biber may not produce the warnings shown above, but may instead show other cryptic messages or produce no output and no messages at all.

The solution is the same as for the infamous cache bug: Delete the cache as explained in Biblatex/biber fails with a strange error about missing recode_data.xml file. Then rerun Biber and let it regenerate the cache. Do not kill that first Biber run after you deleted the cache: It will take a lot longer than usual, because the cache needs to be recreated.

In case the cache creation consistently goes wrong or is directly stopped by security software or rights restrictions, it may be possible to redirect the cache location as described in Biber not running - located in PATH, no error messages with compilation, biber --help produces no output.

Check Your .bib file

In some regards Biber is less forgiving than BibTeX when it comes to wrongly-formatted .bib files.

There are two ways a malformed .bib file can manifest itself. Either Biber gets the hiccups while trying to compile the .bib file, or the .bib file is successfully compiled to the needed .bbl, but you get into trouble when LaTeX tries to read it.

If Biber cannot run on your .bib it will do its best to assist you in finding the culprit. You will find a warning or error message along the lines of

ERROR - BibTeX subsystem: C:\Users\<User>\AppData\Local\Temp\E5geEvmVXt\<filename>.bib_2040.utf8, line 19, syntax error: found "(", expected ","

While the error is reported not in your original file <filename>.bib but some auxiliary file, the line number often comes close to where the error is in your actual file. Keep in mind that the line number indicated there need not necessarily coincide with the line that introduced the real error. You should always check the lines above and below, as well as the .bib entries where the line occurs along with the surrounding entries. Sometimes a opening or closing brace or comma only has a knock-on effect that shows its effects a few lines later. As always with TeX errors can have trickle down effects, so you should focus on the first error/warning in the log.

To make Biber more talkative you can call it with the --debug or even --trace options (see also How to make Biber also print the debug information in the log file?). Additional information will be written to the .blg (log) file. The output of --trace is so rich of information, however, that it is easy to get lost in a sea of 11K lines for a small .bib file. The --debug info can prove very useful to find bad entries in your file, though.

Often, though, a malformed .bib does not actually cause a real error, but only a (or indeed many) warning(s). It is therefore beneficial to have a closer look at the warnings as well.

The following file (@book(bad, should be @book{bad,)

@book{good1,
  author       = {Uthor, Anne},
  title        = {No Trouble Here},
  date         = {2005-10-16},
}
@book(bad,
  author       = {Uthor, Anne},
  title        = {Oohhh, the Wrong Bracket Was Used},
  date         = {2005-10-16},
}
@book{good2,
  author       = {Uthor, Anne},
  title        = {Again, No Problem},
  date         = {2005-10-16},
}

Produces only the warning

line 10, warning: entry started with "(", but ends with "}"

If Biber consumes your .bib file happily and issues no warning, you can still get in trouble if the output written to the .bbl is faulty. Often spacial characters that are left unescaped can lead to nasty errors.

In case Biber cannot point you to the source of the problem, you will have to try and find it yourself. A good way to isolate the troublemaker is the binary search method (as explained in I've just been asked to write a minimal example, what is that?), keep in mind that because the bibliography involves intermediate files, you will have to run the full cycle of pdflatex -> biber -> pdflatex -> pdflatex to be sure that the problem is gone (or not).

There are many possible causes of error when writing a .bib file, but by far the most common things to check are

  • Curly braces,
    • Curly braces for fields. Most field contents must be wrapped in curly braces or quotation marks (only double quotes " are allowed, two single quotes '' might look similar, but will cause errors). The only exception are BibTeX macros (no braces allowed) and plain integers (braces optional, but strongly recommended for biblatex).
    • There must be an opening curly brace between entry type and entrykey, and there must be a closing curly brace at the end.
    • Curly braces must match. You should always have as many opening curly braces as closing curly braces.
  • Commas.

If you got this far and still experience a problem, the best way to debug is to try and come up with an MWE/MWEB, hopefully you will isolate the problematic entry (or entries) that way.

Related Question