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
- Installation issues
- Usage issues
- Version mismatches
- Cache issues
- 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.
Best Answer
Here is a MWE (not really minimum, but showing some options) that should get you started. Other possible values for the
biblatex
options are described in the biblatex documentation.To compile you should now call
pdflatex
,biber
,pdflatex
.biber
operates on the.bcf
file, so either usebiber %.bcf
or (even better) justbiber %
, where%
stands for the basename of your main.tex
file.biblatex-examples.bib
is a file that comes with your TeX distribution, you can find it atTEXMF/bibtex/bib/biblatex.biblatex-examples.bib
or online. It can be used for testing. Use a different filename for your own.bib
file.The
natbib=true
option allows you to usecitep
andcitet
style citations in you text. This is mainly for compatibility with old code. For new code, use\textcite{}
and\parencite{}
instead.biblatex
knows some more cite commands like\autocite{}
or\footcite{}
. These are described in the biblatex documentation.