Token not allowed in PDFDocEncoded string

The package hyperref produces this error when it doesn’t know how to make something into a “character” that will go into one of its PDF entries. For example, the (unlikely) sequence

\newcommand{\filled}[2]{%
  #1%
  \hfil
  #2%
}
\section{\filled{foo}{bar}}

provokes the error. Hyperref goes on to tell you:

removing `\hfil' on input line ...

It’s not surprising: how would you put the typesetting instruction \hfil into a PDF bookmark?

Hyperref allows you to define an alternative for such things: the command \texorpdfstring, which takes two arguments — the first is what is typeset, the second is what is put into the bookmark. For example, what you would probably like in this case is just a single space in the bookmark; if so, the erroneous example above would become:

\newcommand{\filled}[2]{%
  #1%
  \texorpdfstring{\hfil}{\space}%
  #2%
}
\section{\filled{foo}{bar}}

and with that definition, the example will compile succesfully (hyperref knows about the macro \space).

FAQ ID: Q-texorpdf