wmjordan/PDFPatcher · error · FileNotFoundException

无法加载字体：{n}

Error message

无法加载字体：{n}

What it means

ReplaceFontProcessor.LoadFonts throws FileNotFoundException when, after attempting to load a substitute font by name (and falling back through __AlternativeFonts), the iTextSharp BaseFont is still null — meaning the font file could not be located or opened. The exception message names the offending font. A catch block logs '无法加载字体' (cannot load font) and rethrows.

Source

Thrown at App/Processor/ContentProcessors/ReplaceFontProcessor.cs:357

								FontRef = context.Pdf.AddPdfObject(new PdfDictionary()),
								DescendantFontRef = context.Pdf.AddPdfObject(new PdfArray()),
								Vertical = v,
							};
							var fd = f.Locate<PdfDictionary>(PdfName.DESCENDANTFONTS, 0, PdfName.FONTDESCRIPTOR);
							if (fd != null) {
								var num = fd.GetAsNumber(PdfName.ITALICANGLE)?.DoubleValue ?? 0d;
								if (num != 0) {
									nf.ItalicAngle = num;
								}
							}
							if (fs != null) {
								SetupFontSubstitutionMaps(nf, fs);
							}
							if (sn == null && p != -1 && nf.Font.BaseFont == null) {
								nf.Font = _fontFactory.GetFont(__AlternativeFonts[p], v ? BaseFont.IDENTITY_V : BaseFont.IDENTITY_H);
							}
							if (nf.Font.BaseFont == null) {
								throw new FileNotFoundException("无法加载字体：" + n);
							}
							_newFonts.Add(new FontId(n, v), nf);
						}
						catch (Exception) {
							Tracker.TraceMessage(Tracker.Category.Error, "无法加载字体");
							throw;
						}
					}
					r[item.Key] = nf.FontRef;
					if (_fontInfoMap.ContainsKey(fr.Number) == false) {
						var fi = new FontInfo(f, fr.Number);
						_fontInfoMap.Add(fr.Number, fi);
						try {
							ReadSingleByteFontWidths(f, fi, nf);
							ReadCidFontWidths(f, fi, nf);
						}
						catch (NullReferenceException) {
							Tracker.TraceMessage(Tracker.Category.ImportantMessage, $"字体“{n}”的 CID 宽度表错误。");

View on GitHub (pinned to 4782bbd9ad)

Solutions

1. Install the missing font (named in the exception message) on the system or in the app's font folder.
2. Configure a font substitution mapping (FontSubstitution) so the missing font maps to an available one.
3. Ensure the __AlternativeFonts fallback list includes a suitable replacement and that those files exist.
4. Verify the font file path and that the process has read permissions.
5. If embedding legacy CJK fonts, confirm the legacy font files ship with the application.

Example fix

// before
nf.Font = _fontFactory.GetFont(sf ?? n, v ? BaseFont.IDENTITY_V : BaseFont.IDENTITY_H);
if (nf.Font.BaseFont == null)
  throw new FileNotFoundException("无法加载字体：" + n);

// after
nf.Font = _fontFactory.GetFont(sf ?? n, v ? BaseFont.IDENTITY_V : BaseFont.IDENTITY_H)
  ?? _fontFactory.GetFont(__DefaultFallbackFont, v ? BaseFont.IDENTITY_V : BaseFont.IDENTITY_H);
if (nf.Font.BaseFont == null) {
  Tracker.TraceMessage(Tracker.Category.Warning, $"字体不可用，跳过：{n}");
  goto BYPASSFONT;
}

if (!FontUtility.InstalledFonts.Any(f => f.DisplayName == fontName)
    && !File.Exists(Path.Combine(fontDir, fontName + ".ttf")))
    return; // skip replacement

static bool IsFontAvailable(string name) =>
    FontUtility.InstalledFonts.Any(f => f.DisplayName == name);

try { LoadFonts(context, fonts); }
catch (FileNotFoundException ex) {
  Tracker.TraceMessage(Tracker.Category.Error, $"缺少字体，跳过：{ex.Message}");
}

When it happens

Trigger: Running font replacement on a PDF whose embedded/legacy font name is not installed on the system and is not in the __AlternativeFonts fallback list. The code calls _fontFactory.GetFont(name, encoding) which returns a Font with BaseFont==null when the TTF/OTF cannot be found, and the guard at line 356-358 converts that into FileNotFoundException.

Common situations: Processing a PDF referencing a CJK or legacy font (e.g. a subset-prefixed name) that isn't installed on the machine; missing font files in the application's font directory; a font name with encoding issues (vertical '-V' variant) that doesn't match an installed file; deployed environment lacking the required font assets.

Related errors

• 无法匹配与指定尺寸及页码范围相符的页面。
• 转换精度不能小于 0 或大于 6。
• 尺寸单位无效。
• 页面缺少 MediaBox。
• 找不到信息文件。

AI-assisted analysis of wmjordan/PDFPatcher@4782bbd9ad (2026-08-13). Data as JSON: /api/errors/716067ea79677b83. Report an issue: GitHub.