Skip to content

Duplicate font file

Two font registry declarations claim one filename. The build stops rather than letting them compete for a single entry in the archive.

What it looks like

A font of your own in fonts/, registered under a name Keystone already uses:

my-serif:
  main:
    file: DejaVuSerif.ttf
  css: '"My Serif", "Georgia", serif'

ERROR: fonts 'dejavu-serif' and 'my-serif' both declare 'DejaVuSerif.ttf'
  dejavu-serif: main.file
  my-serif: main.file
  An embedded font is addressed by its filename alone, so one name cannot stand
  for two declarations.
  'dejavu-serif' is one of Keystone's own fonts, so rename your file in fonts/
  and the entry that names it.
  See https://keystone.knight-owl.dev/errors/duplicate-font-file/#two-entries-naming-one-file

Or two names that a filesystem would fold into one:

my-serif:
  main:
    file: MySerif.otf
  css: '"My Serif", "Georgia", serif'

my-sans:
  main:
    file: myserif.otf
  css: '"My Sans", "Verdana", sans-serif'

ERROR: fonts 'my-sans' and 'my-serif' declare 'myserif.otf' and 'MySerif.otf',
  which differ only in case
  my-sans: main.file
  my-serif: main.file
  An embedded font is addressed by its filename alone, and the filesystems a
  book is unpacked onto do not all distinguish case, so one name cannot stand
  for two declarations.
  Rename one of the files, and the entry that names it, so the two differ by
  more than case.
  See https://keystone.knight-owl.dev/errors/duplicate-font-file/#names-that-differ-only-in-case

Or one family naming the same file for two of its variants:

my-serif:
  main:
    file: MySerif-Regular.otf
    bold: MySerif-Regular.otf
  css: '"My Serif", "Georgia", serif'

ERROR: font 'my-serif' declares 'MySerif-Regular.otf' twice
  main.file
  main.bold
  Each variant of a family is its own file; one file cannot be two of them.
  Name the missing variant's file, or remove the field when the family ships no
  such variant — an absent variant already falls back to the regular.
  See https://keystone.knight-owl.dev/errors/duplicate-font-file/#one-entry-naming-a-file-twice

What it means

An EPUB keeps its fonts in one flat folder and addresses each by filename alone. Two declarations of one name compete for a single slot: the archive ends up with one file and two manifest entries pointing at it. EPUB validation rejects that, and so does any store that runs it on upload. Whichever file was copied last is the one that survives, so the other family renders in a typeface it never asked for.

Case does not separate two names either. A reader unpacks the archive onto its own filesystem, and the common ones hold MySerif.otf and myserif.otf as one file — as does your own fonts/ directory on macOS or Windows.

Nothing in your source shows this. The names look distinct, and a PDF build has no flat folder to collide in, so one project can build cleanly for print and produce a broken EPUB. Keystone stops at the registry instead.

Two entries naming one file

Two keys, each declaring the same filename. Most often one of them is Keystone's own: the built-in families are registered under the filenames their upstream packages ship, and a font you add under one of those names collides with it.

Rename your file, or drop the surplus entry

When one of the two entries is Keystone's own, yours is the one to change: rename your file in fonts/ and in main.file, or, if your entry points at the image's own copy through main.path, delete the entry. When both are yours and name one file, one is surplus: delete it. A second name for a single font costs nothing as a shortcut.

Names that differ only in case

Two declarations whose filenames match once case is set aside. On a case-sensitive disk these are two files and the build would have worked; on the reader's they are one, so the archive is built for the worse of the two.

Rename one until the two differ by more than case

Changing the spelling is not enough — pick a name that stands apart with case ignored, and update the entry that names it. If the two are meant to be one font, keep a single entry and reach for a shortcut for the second name.

One entry naming a file twice

One key, naming a file for two of its variants — usually bold or italic set to the regular, to stop a reader synthesizing one.

Name the variant's file, or remove the field

Point bold at the family's bold file. If the family ships no bold, remove the field: an absent variant already falls back to the regular, which is what naming it twice was reaching for. See Custom fonts.

  • Custom fonts — registering your own typeface, and what else Keystone checks about an entry.
  • Missing font license — an embedded font whose terms the archive does not carry.
  • Unrecognized font family — a fontfamily no entry defines, which falls back with a warning rather than stopping.