Mrthfx

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)?

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. 
   The infamous cache bug (should be irrelevant for Biber versions >= 2.2)


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.)

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).

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>AppDataLocalTempE5geEvmVXt<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.
  
  
  
  
  • There should always be a comma after the field declaration. (The comma after the very last field is strictly speaking optional, but it is an extremely good idea to include it as well.)
  
  
  • There must also be a comma after the entrykey.
  
  
  • Commas are also special in name fields: How should I type author names in a bib file?, How to properly write multiple authors in bibtex file?.
  
  
  
  

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.

I am not sure if video tutorials about LaTeX are appreciated by the
pro users here. Nevertheless, I think they can be a good help for beginners
for understanding the workflow.

I had a hard time to get BibLaTeX running when I started using it. I also had a hard time with BibTeX before. I learned it mainly from books and for the finer details by using this community.

Over a couple of years, I sometimes give LaTeX introductions to Ph.D. students at work, before that I gave it at my university. I never covered the bibliography stuff in the LaTeX introduction so far because it is too much for a beginner for one afternoon in my opinion.

Later (late 2016) I made a video tutorial for my specific setting which is the LaTeX editor Texmaker.

First Steps

https://www.youtube.com/watch?v=ZYvS52511oQ

Hyperlinks and Multiple Book Authors

https://www.youtube.com/watch?v=t9lyME-Lpak

In this videos, I use the ISO-8859-1 encoding with should work for
European languages. If you are not happy with that encoding, then you
can adapt the encoding to your preference.

I was stuck for a while with a silent crash where biber did not produce any error message and did not produce any output file. Even activating --trace and --debug did not help.

biber output stopped after INFO - Found BibTeX data source ...

I finally used strace to find out that some error message about a Perl module and ISBN is making biber crash. (No idea why this error message is logged to a file on /tmp/ and then deleted without making it visible.)

This is a bug that has been solved in recent versions and is discussed here:
https://github.com/plk/biber/issues/183

If you can upgrade, upgrading to 2.8 solves the problem.

If you cannot upgrade, it helped me to install the perl ISBN module (perl-business-ISBN on SuSe, I assume other distributions have similar packages).