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
Biblatex/biber fails with a strange error about missing recode_data.xml file,
Error message when using biber
Major problem with biblatex/biber
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)?
Since Biber and
biblatexare integrated so closely it is not always entirely clear if the problem you are facing is a Biber problem or a
There are at least five primary sources of trouble when using Biber
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
biblatexor even your
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 (
.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
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
tlmgrrespectively. 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.texneeds to be compiled with at least
Note that the calls above do not include the file extension, a correct call for Biber is either
In particular the call to Biber is independent of the name of your
.bibfile (you do not run Biber on your
.bibfile). You do not call Biber on the
.auxfile. Both forms
biber test.bcfend up running on the
.bcffile, 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
.bcffile, through which
biblatexand Biber communicate, needs to be created.
means that Biber can not find the
.bcffile. There are several possible causes for that message.
.bcffile was created.
.texfile so that the
.bcfcould not be written.
.bibfile and not on the base name of your
.bcfto 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
pdflatex testsequence 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
.auxfile, which is what you do with BibTeX.
If you get a message such as
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.
If Biber was run on your document, you should be able to find a
.blgfile in the directory, that file is Biber's log file. On Windows systems a
.blgfile 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
.blgcreated 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
.blgfile 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
When you run Biber you might find the following warning in the console output and
This tells you that the versions of Biber and
biblatexyou are using do not match. In actual fact it tells you that the version of the
biblatexdoes not agree with the version expected by Biber. Note that the control file version does not necessarily agree with either your version of
biblatexor Biber. The current version of
biblatexfor example is 3.10, Biber is on 2.10 and the biblatex control file version is 3.4.
biblatex control file(this refers to the
.bcffrom above) is the medium
biblatexand Biber use to communicate (it is in fact a bit one-sided:
biblatextells 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
biblatexversion 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
Please refer to the
biblatexmanual or the Biber documentation for the compatibility matrix of matching versions.
If you have installed
biblatexand Biber via your distribution's package manager, all you need is to run an update. ((
tlmgr update --self --allfor 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.)
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
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
biblatexas well, see the point above).
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.
In some regards Biber is less forgiving than BibTeX when it comes to wrongly-formatted
There are two ways a malformed
.bibfile can manifest itself. Either Biber gets the hiccups while trying to compile the
.bibfile, or the
.bibfile is successfully compiled to the needed
.bbl, but you get into trouble when LaTeX tries to read it.
If Biber cannot run on your
.bibit will do its best to assist you in finding the culprit. You will find a warning or error message along the lines of
While the error is reported not in your original file
<filename>.bibbut 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
.bibentries 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
--traceoptions (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
--traceis so rich of information, however, that it is easy to get lost in a sea of 11K lines for a small
--debuginfo can prove very useful to find bad entries in your file, though.
Often, though, a malformed
.bibdoes 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 (
Produces only the warning
If Biber consumes your
.bibfile happily and issues no warning, you can still get in trouble if the output written to the
.bblis 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 -> pdflatexto be sure that the problem is gone (or not).
There are many possible causes of error when writing a
.bibfile, but by far the most common things to check are
"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
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.