Watermark Font Issues in PicList: Causes and Solutions

Watermark font issues in PicList occur when the built-in TrueType font file is missing, corrupted, or fails to download, causing the application to silently skip the watermark step during image uploads.

PicList (kuingsmile/piclist) generates text-based watermarks by rendering SVG overlays using a bundled TrueType font. When the font file becomes unavailable, the watermark feature fails silently, leaving images uploaded without the expected text overlay.

Why Watermark Fonts Fail in PicList

PicList adds watermarks by rendering SVG text using a built-in TrueType font. According to the PicList source code, the application checks for the presence of this font file at startup. If the file is absent, PicList attempts to download it automatically from the repository.

Common Failure Points

Several issues can interrupt this process:

• Network interruptions – The automatic download may timeout or be blocked by firewalls, leaving the font file absent.
• File corruption – A partially downloaded or corrupted font.ttf cannot be read by the renderer, triggering a silent fallback.
• Manual deletion – Users clearing app data may unintentionally remove the font from the data directory.

When any of these conditions occur, PicList silently skips the watermark operation rather than throwing an error. This behavior is documented in FAQ_EN.md (line 100) and was the root cause of issue #188.

How to Fix Watermark Font Issues in PicList

Restore Network Connectivity

Ensure your internet connection is stable and retry the watermark operation. This allows PicList to trigger the automatic download mechanism defined in the font utility functions.

Manual Font Installation

If automatic downloads fail, manually place the font file in PicList's data directory:

1. Download font.ttf from the repository at https://github.com/kuingsmile/piclist/blob/dev/resources/font.ttf
2. Copy the file to:
   • Windows: %APPDATA%/PicList/font.ttf
   • macOS/Linux: ~/.config/PicList/font.ttf

This guarantees the renderer finds a valid font file at runtime.

Clear Corrupted Font Cache

Delete the existing font.ttf from the data folder, then restart PicList and trigger a watermark operation. This removes potentially corrupted data and forces a fresh download.

Use Custom Fonts

Bypass the built-in font entirely by specifying a custom path in the configuration. The watermark settings are defined in src/universal/types/types.d.ts and mapped through src/renderer/utils/configPaths.ts and src/main/utils/configPaths.ts using the key buildIn.watermark.fontPath.

// Override the default font path in PicList's config
import { getConfig, setConfig } from 'piclist'

const cfg = await getConfig()
cfg.buildIn.watermark.fontPath = '/absolute/path/to/your/custom-font.ttf'
await setConfig(cfg)

Force Font Re-download

For programmatic recovery, call the download utility directly from the main process:

// Force a font re-download
import { downloadBuiltinFont } from 'piclist/lib/watermark/font'

await downloadBuiltinFont()   // pulls the default font from the CDN

This function is part of the watermark font handling system referenced in CHANGELOG.md regarding fixes for issue #188 (line 744).

Key Source Files

Understanding these files helps diagnose persistent issues:

• src/universal/types/types.d.ts – Defines the TypeScript interfaces for watermark options, including the fontPath property.
• src/renderer/utils/configPaths.ts – Handles configuration path resolution in the renderer process.
• src/main/utils/configPaths.ts – Mirrors the path mapping on the main process side, ensuring both UI and backend read identical configurations.
• FAQ_EN.md – Documents the automatic font check and download behavior.
• CHANGELOG.md – Records bug-fix commits related to watermark font handling.

Summary

• Watermark font issues in PicList result from missing, corrupted, or unreadable TrueType font files in the application data directory.
• The application attempts automatic downloads when fonts are missing, but network issues or corrupted files can cause silent failures.
• Fixes include ensuring stable internet, manually installing the font to %APPDATA%/PicList/font.ttf or ~/.config/PicList/font.ttf, clearing corrupted caches, or using custom fonts via buildIn.watermark.fontPath.
• Configuration paths are managed consistently across renderer and main processes through dedicated utility files.
• Re-installing PicList restores default resources if manual interventions fail.

Frequently Asked Questions

Where does PicList store the watermark font file?

PicList stores the font file as font.ttf in the application data directory: %APPDATA%/PicList/font.ttf on Windows and ~/.config/PicList/font.ttf on macOS or Linux. The application checks this location before attempting to render SVG watermarks.

Why does PicList skip the watermark without showing an error?

When the font file is missing or corrupted, PicList's watermark renderer falls back to skipping the overlay rather than failing the entire upload operation. This silent behavior prevents upload interruptions but can confuse users expecting to see text watermarks, as documented in the FAQ and issue #188.

Can I use a custom font instead of the built-in one?

Yes. Set the buildIn.watermark.fontPath configuration property to point to any local TrueType font file. This setting is accessible through PicList's config API and overrides the default font download mechanism entirely.

How do I force PicList to re-download the font?

Delete the existing font.ttf from the data directory and restart the application, or programmatically call downloadBuiltinFont() from piclist/lib/watermark/font in the main process. This function pulls the default font from the CDN and replaces any corrupted or missing files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}