Skip to content

fix(ytdlp): cap title length in default filename template - #258

Merged
krau merged 1 commit into
krau:mainfrom
ilhamsyahids:fix/ytdlp-long-filename
Nov 16, 2026
Merged

krau merged 1 commit into
krau:mainfrom
ilhamsyahids:fix/ytdlp-long-filename

Conversation

@ilhamsyahids

Copy link
Copy Markdown
Contributor

Problem

yt-dlp downloads fail for posts whose caption becomes the title, because the default output template %(title)s.%(ext)s has no length limit:

ERROR: unable to open for writing: [Errno 36] Filename too long: 'cache/ytdlp-3076279808/3.9K_views_3.3K_reactions_Cita-cita_terbesar_kita_..._Fawaid_Nasehat.m4a.part'

That title is about 330 bytes. Linux caps a file name at 255 bytes (NAME_MAX), and yt-dlp also appends .fNNN and .part while downloading.

Fix

Change DefaultYtdlpFilenameTemplate to %(title).200B.%(ext)s. yt-dlp's B modifier truncates by bytes, not characters, and doesn't split multi-byte UTF-8 sequences, so this also holds for non-Latin titles when restrict_filenames is off. The 55 bytes left over cover the extension and the temporary suffixes.

Custom templates set through ytdlp.filename_template or -o are unchanged.

Also updated:

  • the filename template placeholder in the web settings (web/ui/src/settingsFields.ts)
  • docs/content/{en,zh}/usage/ytdlp.md

Testing

core/tasks/ytdlp/output_test.go renders the default template with the local yt-dlp from an info JSON (--load-info-json --print filename), so no network is used. It checks that a long ASCII title and a long Arabic title both fit in 255 bytes with the download suffixes added. The test is skipped when yt-dlp isn't installed.

  • With the old template: fails at 494 bytes (ASCII) and 814 bytes (Arabic).
  • With the new template: passes.

go test ./core/tasks/ytdlp/ and go vet pass.

The same change has been running on a v0 deployment, where the title from the error above now produces a 204-byte name.

Note

On an existing install, ytdlp.filename_template is a stored setting. If the old default was saved to the database, it keeps it until changed in Settings. New installs get the new default.

Long post captions used as titles produced names over the 255-byte
NAME_MAX limit, so yt-dlp failed with "[Errno 36] Filename too long".
Truncate the title to 200 bytes in the default template, leaving room
for the extension and the .fNNN/.part suffixes yt-dlp appends.

Signed-off-by: Ilham Syahid S <ilhamsyahids@gmail.com>
@ilhamsyahids
ilhamsyahids marked this pull request as ready for review November 16, 2026 10:01
@krau
krau merged commit 42f9192 into krau:main Nov 16, 2026
3 checks passed
@ilhamsyahids
ilhamsyahids deleted the fix/ytdlp-long-filename branch November 16, 2026 14:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants