Undefined control sequence when compiling with `XeLaTeX`

[alexedding]

Hello, thank you for maintaining fontawesome7!

I would like to report an issue I have run into recently. Unfortunately, I am unfamiliar with L3 and unsure how to go about debugging it.

Overview

Compiling certain fontawesome*-defined control sequences with XeLaTeX fails with

! Undefined control sequence.

The issue is mainly present in fontawesome6 (69 commands) and fontawesome7 (79 commands). Still, there are also 2 such commands in fontawesome5, but none in fontawesome.

Compiling with XeLaTeX succeeds when these \fa* commands are replaced with their corresponding \faIcon{...} commands. Alternatively, compiling with LaTeX or LuaLateX succeeds, provided the rest of the document does.

Minimum Working Example to Reproduce the Problem

Compiling the file below with latexmk -xelatex fails, whereas latexmk -pdftex or latexmk -lualatex succeeds.

\documentclass{article}
\usepackage{metalogo}
% TODO Comment/Uncomment the appropriate package
\usepackage{fontawesome7}
% \usepackage{fontawesome6}
% \usepackage{fontawesome5}
\title{\XeLaTeX\ and \texttt{fontawesome*}}
\author{John Doe}
\date{2026.06.22}
\begin{document}
\maketitle

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Control group}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
The control sequence in this section is only used as a sanity check that
something works when compiling with \XeLaTeX:

\bigskip\noindent%{{{
\verb|\faAccessibleIcon| \faAccessibleIcon\\
% }}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{\texttt{fontawesome5}, \texttt{fontawesome6} and \texttt{fontawesome7}}
% TODO Comment out the other sections when testing for `fontawesome5`.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
The control sequences in this section fail for \texttt{fontawesome5},
\texttt{fontawesome6} and \texttt{fontawesome7} when compiling with \XeLaTeX.

\bigskip\noindent%{{{
\verb|\faFaucet| \faFaucet\\
\verb|\faFirefoxBrowser| \faFirefoxBrowser\\
% }}}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{\texttt{fontawesome6} and \texttt{fontawesome7}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
The control sequences in this section fail for \texttt{fontawesome6} and
\texttt{fontawesome7} when compiling with \XeLaTeX.

\bigskip\noindent%{{{
\verb|\faAsterisk| \faAsterisk\\
\verb|\faAt| \faAt\\
\verb|\faA| \faA\\
\verb|\faBacteria| \faBacteria\\
\verb|\faBacterium| \faBacterium\\
\verb|\faBoxTissue| \faBoxTissue\\
\verb|\faB| \faB\\
\verb|\faCloudflare| \faCloudflare\\
\verb|\faC| \faC\\
\verb|\faDailymotion| \faDailymotion\\
\verb|\faDeezer| \faDeezer\\
\verb|\faDollarSign| \faDollarSign\\
\verb|\faD| \faD\\
\verb|\faEdgeLegacy| \faEdgeLegacy\\
\verb|\faEquals| \faEquals\\
\verb|\faExclamation| \faExclamation\\
\verb|\faE| \faE\\
\verb|\faFaucetDrip| \faFaucetDrip\\
\verb|\faF| \faF\\
\verb|\faGooglePay| \faGooglePay\\
\verb|\faGreaterThan| \faGreaterThan\\
\verb|\faG| \faG\\
\verb|\faHandHoldingMedical| \faHandHoldingMedical\\
\verb|\faHandSparkles| \faHandSparkles\\
\verb|\faHandsBubbles| \faHandsBubbles\\
\verb|\faHandshakeSlash| \faHandshakeSlash\\
\verb|\faHashtag| \faHashtag\\
\verb|\faHeadSideCough| \faHeadSideCough\\
\verb|\faHouseChimneyWindow| \faHouseChimneyWindow\\
\verb|\faHouseSignal| \faHouseSignal\\
\verb|\faH| \faH\\
\verb|\faIdeal| \faIdeal\\
\verb|\faI| \faI\\
\verb|\faJ| \faJ\\
\verb|\faK| \faK\\
\verb|\faLessThan| \faLessThan\\
\verb|\faL| \faL\\
\verb|\faMicroblog| \faMicroblog\\
\verb|\faMixer| \faMixer\\
\verb|\faM| \faM\\
\verb|\faN| \faN\\
\verb|\faO| \faO\\
\verb|\faPercent| \faPercent\\
\verb|\faPlus| \faPlus\\
\verb|\faP| \faP\\
\verb|\faQuestion| \faQuestion\\
\verb|\faQ| \faQ\\
\verb|\faRust| \faRust\\
\verb|\faR| \faR\\
\verb|\faShopify| \faShopify\\
\verb|\faSquareInstagram| \faSquareInstagram\\
\verb|\faSquarePiedPiper| \faSquarePiedPiper\\
\verb|\faS| \faS\\
\verb|\faTemperatureArrowDown| \faTemperatureArrowDown\\
\verb|\faTemperatureArrowUp| \faTemperatureArrowUp\\
\verb|\faTiktok| \faTiktok\\
\verb|\faTrailer| \faTrailer\\
\verb|\faT| \faT\\
\verb|\faUnity| \faUnity\\
\verb|\faUnsplash| \faUnsplash\\
\verb|\faU| \faU\\
\verb|\faV| \faV\\
\verb|\faW| \faW\\
\verb|\faX| \faX\\
\verb|\faY| \faY\\
\verb|\faZ| \faZ\\
% }}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{\texttt{fontawesome7}}
% TODO Comment out this section when NOT testing for `fontawesome7`.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
The control sequences in this section fail for \texttt{fontawesome7} when
compiling with \XeLaTeX.

\bigskip\noindent%{{{
\verb|\faBots| \faBots\\
\verb|\faGuilded| \faGuilded\\
\verb|\faHeadSideCoughSlash| \faHeadSideCoughSlash\\
\verb|\faHive| \faHive\\
\verb|\faInstalod| \faInstalod\\
\verb|\faOctopusDeploy| \faOctopusDeploy\\
\verb|\faPerbyte| \faPerbyte\\
\verb|\faUncharted| \faUncharted\\
\verb|\faWatchmanMonitoring| \faWatchmanMonitoring\\
\verb|\faWirsindhandwerk| \faWirsindhandwerk\\
\verb|\faWodu| \faWodu\\
% }}}

% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \section{\texttt{fontawesome6} (removed from \texttt{fontawesome7}?)}
% % TODO Comment out this section when NOT testing for `fontawesome6`.
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% The control sequence in this section fails for \texttt{fontawesome6} when
% compiling with \XeLaTeX. However, it seems removed from
% \texttt{fontawesome7}, at least it does not appear in the
% \texttt{fontawesome7-mapping.def} file.
%
% \bigskip\noindent%{{{
% \verb|\faHandshakeSimpleSlash| \faHandshakeSimpleSlash\\
% % }}}

\end{document}

Specifications

• fontawesome* versions:
  • fontawesome5 2022/05/02 v5.15.4 Font Awesome 5
  • fontawesome6 2025/09/16 v6.7.2-3 Font Awesome 6
  • fontawesome7 2025/11/02 v7.1.0-1 Font Awesome 7 (also, GitHub: 5cacbeb)
• Compiler versions:
  • LaTeX2e: 2025-11-01
  • L3 programming layer: 2026-01-19
  • pdfTeX: 3.141592653-2.6-1.40.29 (preloaded format=pdflatex 2026.6.10)
  • XeTeX: 3.141592653-2.6-0.999998 (preloaded format=xelatex 2026.6.10)
  • LuaHBTeX: 1.24.0 (format=lualatex 2026.6.10)
  • TeX Live: 2026/Arch Linux

Thank you again for your time!

[alexedding]

Not sure if this helps, but when considering the codepoints of the affected commands, a pattern seems to be clear. These are all commands:

• corresponding to ASCII characters,
• brand icons with codepoints less than or equal to "E340 (brands0 $\le$ "E340, brands1 $\le$ "E087, and brands2 $\le$ "E2D0), and
• free icons with codepoints less than or equal to "E062 (free0 $\le$ "E05B, free1 $\le$ "E006, free2 $\le$ "E062, free3 $\le$ "52, free4 $\le$ "E041 and free5 $\le$ "5A).

fontawesome_31.txt
fontawesome_all_cs.txt

[alexedding]

For each font file, fontawesome6-utex-helper.sty and fontawesome7-utex-helper.sty iterate from the glyph with GID 67, skipping glyphs with lower GIDs. This seems to be carried over from fontawesome5.

for otf in /usr/share/texmf-dist/fonts/opentype/public/fontawesome5/FontAwesome5*.otf; do
  otfinfo -g "$otf" | head -67
  echo "..."
  otfinfo -u "$otf" | grep -E ' (65|66|67) '
  echo "---"
done

suggests that this was an off-by-one exclusion of Latin alphanumeric, hyphen, space, and period, which also excluded faucet, firefox-browser and heart. However, heart was only excluded from FontAwesome5Free-Regular-400.otf, and not from FontAwesome5Free-Solid-900.otf, as it has GID 103 in the latter. The glyph ordering is different for FontAwesome6 and FontAwesome7, resulting in the issue above. If there is a need to exclude some glyphs, e.g. digits, this might be achieved more robustly using scripts/generate_binding.py.

EDITs: Corrected ironic off-by-one errors in the reported numbers, rephrased and adjusted the commands to avoid such errors.