Skip to main content

Youtarr Troubleshooting Guide

Collecting Logs​

Youtarr writes its log to the container console (docker logs youtarr) and to rolling files in config/logs/ (youtarr.1.log, youtarr.2.log, ...; the highest number is the newest).

To capture a problem:

  1. Open Settings -> Logging, set Log level to Debug, and save. No restart is needed.
  2. Reproduce the problem.
  3. Click Download logs to save all log files as one file, or copy the files from config/logs/ on the host.
  4. Set Log level back to Default and save.

Download logs replaces the API keys and tokens saved in Settings, token parameters in URLs, and proxy passwords with [REDACTED]. The files in config/logs/ are not changed. Logs can still include video titles, channel names, file paths and server addresses, so check them before posting them publicly.

Login Issues​

Cannot Find the Setup Token​

Problem: First-time setup wizard asks for a token and you don't know where to find it.

See Authentication - Cannot Find the Setup Token for the full list of solutions.

Forgotten Admin Password​

Problem: Cannot log in because you've forgotten the admin password.

Solution:

Method 1: Using Environment Variables (Recommended)

  1. Stop Youtarr:

    ./stop.sh
  2. Edit your .env file and set new credentials:

    AUTH_PRESET_USERNAME=admin
    AUTH_PRESET_PASSWORD=your-new-password
  3. Start Youtarr:

    ./start.sh
  4. Log in with the new credentials. Once logged in, you can remove these variables from .env if desired (credentials will persist in config/config.json)

Method 2: Reset via config.json (Requires localhost access)

  1. Stop Youtarr:

    ./stop.sh
  2. Edit ./config/config.json and delete both the username and passwordHash lines

  3. Start Youtarr:

    ./start.sh
  4. Open Youtarr in any browser. You will be prompted to create a new admin account using the one-time setup token from docker logs youtarr or config/setup-token.

Session Expired​

Problem: Getting "Invalid or expired token" errors.

Solution:

  • You will be automatically redirected to the login page
  • Simply log back in with your credentials
  • Sessions expire after 7 days
  • If issues persist, clear browser cache/cookies

Plex API Key Issues​

Problem: Cannot connect to Plex server or refresh library.

Solution:

  1. Get a new API key automatically:

    • Go to Settings -> Plex
    • Click "Get Key" button next to Plex API Key field
    • Log in with your Plex account (must have admin access to your server)
    • Save configuration
  2. Get API key manually:

  3. If you have an invalid/old key:

    • Stop Youtarr: ./stop.sh
    • Edit config/config.json and clear the key: "plexApiKey": ""
    • Restart: ./start.sh
    • Get a new key using method 1 or 2 above

Notifications Not Sending​

Problem: You never receive notifications after downloads (Discord, Slack, Telegram, email, ntfy, or any other service).

Solution:

  1. Open Settings -> Notifications and confirm Enable Notifications is on.
  2. Confirm your service appears in the list of added services. A URL typed into the Notification URL field is only added when you click Add Service (or press Enter); save the settings page afterwards.
  3. Use the test button (paper-plane icon, "Send test notification") next to the service to confirm delivery.
  4. Download notifications are sent when a run downloads at least one new video, or when a run fails with a diagnosed cause or stops early. A run with nothing new and no problems sends nothing.
  5. Check the server logs (docker compose logs -f) for Failed to send notification errors that may indicate network or permission issues.

Test Notification Fails​

Problem: Sending a test notification shows an error.

Solution:

  1. Check the URL format for your service. Notifications are delivered through Apprise, so any Apprise URL works: for example discord://webhook_id/webhook_token, https://discord.com/api/webhooks/..., slack://..., tgram://..., or ntfy://....
  2. Make sure the destination still exists (for example the Discord channel or webhook, Slack channel, or Telegram chat) and that the credentials in the URL still have permission to post.
  3. Retry after checking network/firewall rules that may block outbound requests to the service.

Automatic Video Removal Issues​

Dry Run Preview Fails or Shows "Storage status unavailable"​

Problem: Previewing automatic removal returns an error, or the space-based strategy is disabled.

Solution:

  • Confirm the storage indicator (shown in the app header and at the bottom of the navigation sidebar) is visible and shows valid values. Space-based removal requires the server to resolve the download directory path and gather disk usage via df.
  • Ensure the DATA_PATH (or selected YouTube directory) exists within the container/host and is mounted with read access to filesystem metadata.
  • If you're running on network storage or uncommon mounts, try remounting with df support or rely on age-based or total-size cleanup instead (the total size rule does not use df).
  • Retry the preview after saving the configuration again. The preview endpoint requires a valid auth token; log back in if necessary.

Downloads Stopped with "Downloads are paused"​

Problem: New downloads are refused (HTTP 409 from the API), scheduled downloads show as skipped, and a "Downloads are paused" banner appears.

Solution:

  • If the banner says the downloads folder is empty, does not exist, could not be read, or that most downloaded videos are not where Youtarr saved them, the downloads folder looks unavailable: a drive or network share is not mounted, or the container's volume mapping points at a different folder than your library. Youtarr holds downloads so new files do not land outside your library. See Every Video Shows as Missing After I Moved the Library. Downloads resume on their own once the folder is back.
  • If you moved files around inside the downloads folder yourself, the stored paths are out of date: run Settings -> Maintenance & Rescan -> Rescan files on disk. Downloads resume as soon as the rescan finishes.
  • A storage limit on Settings -> Storage Limits was reached. The banner and the notification say which one and by how much.
  • Usage further past the limit than one video is expected: limits are checked between download jobs, so a job that was already running when the limit was crossed finishes all of its videos first.
  • Free space or remove videos (manually, or with Auto Removal), or raise or clear the limit. Downloads resume on their own: Youtarr re-checks after deletions, on settings changes, and every 5 minutes while paused. Queued downloads then start automatically.
  • If downloads stay paused after an Auto Removal run, check that the pause limits are not stricter than the Auto Removal limits (the Storage Limits page shows a warning when they are).

Nightly Cleanup Didn't Delete Anything​

Problem: Automatic cleanup runs on schedule but no videos are removed.

Solution:

  • Verify Automatic Video Removal is enabled on Settings -> Auto Removal and at least one rule is configured: an age threshold, a free-space threshold, a total size limit, or watched-based removal. Note that watched-based removal only runs while watch status sync is enabled.
  • Remember the exclusions. Videos you've marked as Protected, videos of channels with auto-removal protection enabled, and the newest downloads kept by "Keep this many newest downloads" (the global setting plus any per-channel keep counts) are never removed, so a run can legitimately delete nothing.
  • Run the dry-run preview to see how many videos currently match the rules - it also shows how many videos the protection settings are keeping. Adjust values if needed (for example, lower the free-space threshold or reduce the age requirement).
  • Use Run now on the Automatic video cleanup card in Settings -> Scheduling to see the result immediately (for example 'No videos matched the removal rules'), or check the logs directly with docker compose logs -f youtarr.
  • If errors appear in the logs (e.g., permission issues deleting files), resolve those first - the cron job will skip files it cannot delete.

Library / File Issues​

Videos Show as "Missing" After I Moved or Renamed Files​

Problem: After moving downloaded files to a new location, renaming a folder, or restoring from backup, videos display with a cloud-off icon as if they were deleted.

Solution: Open Settings -> Maintenance & Rescan and click Rescan files on disk. Youtarr walks the downloads folder, matches files by the [<youtube-id>] segment in each filename, and updates the stored paths and "missing" flags. The same scan also runs daily on a schedule and at server startup.

The rescan recognizes .mp4, .webm, .mkv, .m4v, .avi, and .mp3. Files that no longer have the [<youtube-id>] segment in their name (for example, if you renamed Channel - Video [abc123XYZ01].mp4 to My Movie.mp4) cannot be matched and will continue to show as missing.

On a large library on a network share, the scan can take a while (most of an hour on slow disks while backups run). Settings -> Maintenance & Rescan shows how far it has got, and the log prints its progress every 30 seconds.

Every Video Shows as Missing After I Moved the Library​

Problem: After moving the whole library to another folder on the host (or changing the compose file), the rescan says the downloads folder is empty, or that most downloaded videos were not found, and downloads are paused.

Cause: Youtarr only sees the host folder that the container's volume mapping points at (the line ending in :/usr/src/app/data in your compose file). The YOUTUBE_OUTPUT_DIR variable in the environment: section is only the label Youtarr shows for it. If you moved the library and changed only YOUTUBE_OUTPUT_DIR, Youtarr is still looking at the old, now empty, folder.

Solution:

  1. Point the volume mapping at the folder that now holds your library (in our docker-compose.yml that is YOUTUBE_OUTPUT_DIR in .env, which feeds both), then restart Youtarr.
  2. Let the startup rescan finish, or run Rescan files on disk. It finds every video by the [<youtube-id>] in its filename and marks it downloaded again; nothing in the database needs editing.
  3. Until the rescan has finished, do not use Mark all missing as deleted or Empty trash: emptying missing videos from the trash forgets them for good.

Videos that Youtarr downloaded while the mapping pointed at the old folder are still in that old folder on the host. Move them into the library and rescan.

While the downloads folder looks empty, or most videos are not where they were saved, Youtarr marks nothing missing and holds downloads (see "The downloads folder looks unmounted" under Deleted vs. Missing Videos, and Emptying the Trash). Rescan anyway... would mark them all missing, so it says how many videos it would affect and asks you to confirm you removed the files yourself.

Deleted vs. Missing Videos, and Emptying the Trash​

Youtarr keeps a record of every video it has downloaded, even after the file is gone, so the video can be re-downloaded and so automatic downloads do not fetch it again. A video without a file is shown in one of two ways:

  • Deleted (neutral grey chip): Youtarr removed the file on purpose, through a delete in the app or automatic cleanup, or you marked a missing video as deleted. Videos removed before Youtarr started recording the reason also show as Deleted ("Removed before Youtarr recorded why"). The Videos page hides deleted videos by default; the Deleted filter chip (set to "Hide" unless you change it, which is remembered in your browser) and the "N deleted videos hidden. Show" note bring them back. Channel and playlist pages keep listing them.
  • Missing (red chip): Youtarr expected a file on disk and could not find it. Missing videos stay visible so you can look into them. Hover or tap the chip, or open the video, to see the path Youtarr looked at and when.

The downloads folder looks unmounted: if your downloads live on a drive or network share and it is not mounted, every file looks gone. Youtarr checks that the downloads folder (and each __subfolder in it) exists and is not empty before marking anything missing. Because a bare mount point stops being empty as soon as something is written into it, Youtarr also looks for a random sample of downloaded videos where it saved them, and treats the folder the same way when most of them are not there. The rescan judges by what its walk of the folder finds instead: if it finds fewer than half of a folder's downloaded videos (and at least 25 are gone), it marks none of them missing that run and says how many it found.

While a check fails, the Videos page shows a warning instead of marking videos missing, the scheduled rescan records a partial run that names the folder, automatic cleanup records a skipped run instead of stamping videos it cannot reach as deleted, deleting a video in the app is refused with the same message, and downloads are paused (only for the downloads folder itself, not a single __subfolder) so new files do not land outside your library. If missing videos are stored in the failing folder, Empty trash cannot remove them, and Mark all missing as deleted is disabled, or, when the folder is only empty or most videos are not found (not gone or unreadable), asks you to confirm that you removed the files yourself. Failing __subfolders only affect the videos stored in them (every subfolder is checked, so two shares down at once are both covered), and an empty one that no video is stored in (for example one a channel was moved out of) is ignored. Mount the share (or fix the volume mapping) and the warning goes away on its own; nothing was changed in the meantime.

If you moved files inside the downloads folder yourself, run Rescan files on disk instead: it finds them by their [<youtube-id>] and updates the stored paths, and the warnings and the download pause clear when it finishes.

If you really removed the files yourself, use Settings -> Maintenance & Rescan -> Rescan anyway...: it says how many videos it would mark missing, asks you to confirm, then runs the rescan without these checks; then use Mark all missing as deleted. Only do this when you know the files are gone. While at least as many videos are missing as present, Mark all missing as deleted and emptying missing videos from the trash also ask you to confirm that you removed the files yourself.

Mark as deleted: when a missing video's file really is gone, select it on the Videos page and choose Mark as deleted (the video's window has the same button on every page), or use Settings -> Maintenance & Rescan -> Mark all missing as deleted. The record is kept (the video can still be re-downloaded, and a file that turns up again is marked downloaded by the rescan); only how the Videos page treats it changes.

Empty trash (Settings -> Maintenance & Rescan -> Empty trash...) forgets deleted and/or missing videos entirely. You choose which videos (Deleted, Missing, or both) and what happens to the download archive (complete.list): keeping the entries (recommended) means automatic channel and playlist downloads keep skipping those videos; removing them means automatic downloads treat the videos as new and may download them again at the next run. Emptying the trash removes the videos from the Videos page and Download History, makes their channel and playlist pages show them as not downloaded, and removes the watch history Youtarr synced for them from your media servers. No files in your downloads folder are touched, and if a missing video's file turns up later Youtarr will not know about it. This cannot be undone.

If you choose to remove download archive entries, wait for active downloads to finish before emptying the trash. Downloads queued during that purge wait for it to finish. If a purge fails partway, earlier batches remain purged; a batch whose archive cleanup failed stays in the trash so you can fix the error and retry.

I Converted Videos to a Different Format and Youtarr Lost Them​

Problem: You used ffmpeg or another tool to convert downloaded .mp4 videos to .mkv (or another container), and Youtarr now lists those videos as missing.

Solution: Run Settings -> Maintenance & Rescan -> Rescan files on disk. As long as the converted file kept the original [<youtube-id>] segment in its filename and uses one of the supported extensions (.mp4, .webm, .mkv, .m4v, .avi, .mp3), Youtarr will detect the new file, update the stored path, and clear the "missing" flag. See Rescan Files on Disk for full details on supported formats and limitations.

Video Downloads Fine but Never Appears in Plex (Windows Path Length)​

Problem: A video downloads successfully, shows as downloaded in Youtarr, and exists on disk, but it never appears in Plex; if the video belongs to a synced playlist, the logs show Unable to sync item <id> for playlist "..." to <server>: not found on server, skipping.

Cause: When Plex runs on Windows, its scanner silently skips any file whose full path is 260 characters or longer (the Win32 MAX_PATH limit). Youtarr's filename template is used for both the per-video folder and the filename; with the channel folder on top, the channel name appears three times in the full path and the title twice. Combined with your Windows drive and folder prefix, a long channel name plus a long title can cross the limit. The current default template caps titles at 64 bytes (%(title).64B) to keep typical paths well clear of the limit, but installs that saved settings under an older default keep their persisted .74B/.76B value, which can cross it. The file itself is fine: NTFS and File Explorer handle long paths, but Plex's scanner does not. Note that Windows' LongPathsEnabled registry setting does not help, because Plex does not declare itself long-path aware.

Diagnosis: Measure the full path as Plex sees it (drive letter through .mp4). At 260 characters or more, this is your problem.

Solution: Shorten the video's folder and file names on disk, keeping the [<youtube-id>] segment in the filename. Then run Settings -> Maintenance & Rescan -> Rescan files on disk so Youtarr picks up the new path, let Plex scan the library, and (for playlists) run Sync now. To prevent recurrence, shorten the filename template under Settings -> Core -> Naming -> Video filename template: reduce the title truncation to the current recommended %(title).64B (or smaller), or use a preset without the channel-name prefix; see Video Filename Template. Only new downloads are affected; existing files keep their names.

Docker Issues​

"Empty section between colons" Error​

Problem: Getting error invalid spec: :/usr/src/app/data: empty section between colons when trying to start with Docker Compose.

Cause: You ran docker compose up directly instead of using ./start.sh without creating and configuring your .env file. The docker-compose.yml file requires the YOUTUBE_OUTPUT_DIR environment variable to be set, which ./start.sh reads from your config.json.

Solution:

  1. Use the start script instead of running docker-compose commands directly:
./start.sh

The start script:

  • Reads your configured YouTube output directory from config/config.json
  • Exports it as YOUTUBE_OUTPUT_DIR environment variable
  • Then runs docker-compose with the correct configuration
  1. Using docker-compose commands:
  • Ensure that you have created your .env file from the provided .env.example and configured your YOUTUBE_OUTPUT_DIR before attempting to run docker compose up -d
  1. In Portainer: don't deploy the repository's compose file there at all. Use the stack in the Portainer guide, which doesn't need YOUTUBE_OUTPUT_DIR set separately.

Docker Desktop Mount Path Error (Windows)​

Problem: Error message: Error response from daemon: error while creating mount source path '/run/desktop/mnt/host/...': mkdir /run/desktop/mnt/host/...: file exists

This is a known Docker Desktop issue on Windows where mount points become corrupted.

Solutions (try in order):

  1. Restart Docker Desktop:

    ./stop.sh

    Quit Docker Desktop from system tray, restart it, then:

    ./start.sh
  2. Reset WSL2 mounts:

    • Open PowerShell as Administrator
    • Run: wsl --shutdown
    • Restart Docker Desktop
    • Run ./start.sh
  3. Full system restart:

    • If Docker Desktop hangs, restart your entire machine
    • This clears all stale mount points

Prevention:

  • Always use ./stop.sh before shutting down Docker Desktop
  • Disable Windows Fast Startup (Control Panel → Power Options)
  • Let Docker Desktop fully start before running ./start.sh

Container Won't Start​

Problem: Containers fail to start or immediately exit.

Solution:

  1. Check logs:

    docker compose logs -f
  2. Ensure the web port isn't in use:

    netstat -an | grep 3087

"EMFILE: too many open files, watch" or "Cannot watch config.json"​

Problem: Youtarr logs this warning on startup:

Cannot watch config.json for changes; Youtarr will keep running, but hand edits to config.json will not be picked up until restart ...

Older versions crashed on startup instead, with:

Error: EMFILE: too many open files, watch '/app/config/config.json'

Cause: Youtarr watches config.json so it can pick up changes you make to the file by hand. Linux limits how many file watchers (inotify instances) each user can create, and the default is 128. On hosts running many containers as the same user (on Unraid most containers run as nobody), the other containers can use up that shared limit, leaving none for Youtarr. A related limit, fs.inotify.max_user_watches, produces an ENOSPC "System limit for number of file watchers reached" error instead.

Youtarr keeps running without the watcher. Settings saved from the web UI still work; the only thing lost is auto-reload of hand edits to config.json, which take effect after a restart instead.

Solution: Raise the limit on the host (not inside the container):

sysctl -w fs.inotify.max_user_instances=512
# If the warning mentions max_user_watches / ENOSPC:
sysctl -w fs.inotify.max_user_watches=524288

Then restart Youtarr. sysctl -w doesn't survive a reboot. To make it permanent:

  • Unraid: install the Tips and Tweaks plugin and raise the inotify limits there, or add the sysctl -w ... line(s) to /boot/config/go so they run at every boot.
  • Other Linux hosts: create /etc/sysctl.d/99-inotify.conf containing fs.inotify.max_user_instances=512 (and fs.inotify.max_user_watches=524288 if needed), then run sysctl --system.

Asustor App Central: Stuck on an Old Version​

Problem: You installed Youtarr from App Central on an Asustor NAS, a newer Youtarr release exists, but pulling images via Docker or Portainer doesn't update anything.

Solution: This is expected. The App Central package pins the exact Youtarr version in its docker-compose file, so the image tag doesn't change until the package maintainer publishes an updated package and Asustor approves it. That usually happens within a few days of a GitHub release. Update through App Central when the new version appears there; your config, database, and videos are preserved. See the Asustor guide for details.

Database Issues​

Table Corruption After Simultaneous Database and Youtarr Update​

Problem: After updating both your external MariaDB/MySQL and Youtarr at the same time, logs show errors like:

SequelizeDatabaseError: Table 'youtarr.Jobs' doesn't exist in engine

(errno 1932), and/or tables appear empty despite having data before the update.

Cause: When MariaDB upgrades to a new version, it performs internal data file upgrades on startup. If a Youtarr migration runs before that process completes, the combination of a database engine upgrade and an ALTER TABLE happening back-to-back can corrupt tables or cause data loss. This is a MariaDB/InnoDB limitation that affects any application running migrations during a database version change.

Solution: Restart Youtarr. In most cases the table corruption is transient and the health check will recover automatically on restart. The error in the logs may look severe, but the database typically self-heals once MariaDB finishes its internal upgrade. Job/download history may be lost, but channels, videos, and settings are unaffected.

Prevention: Never update your database server and Youtarr at the same time. Update MariaDB first, confirm it is fully running (check its logs for "ready for connections"), then update Youtarr. See the External Database Guide for details.

UTF-8 Character Errors​

Problem: Errors like Incorrect string value: '\\xF0\\x9F\\xA7\\xA1' when channel names or video titles contain emojis.

By default Youtarr creates the database and tables as utf8mb4, so this shouldn't happen unless you are using an external DB. If so, see External Database Guide for how to create your DB with the correct character set.

How to ensure that your DB is using the correct character set:

  1. Check your database character set by connecting to the DB and then running:
    -- Database Character Set
SELECT 'DATABASE' as Object_Type, 'youtarr' as Name, DEFAULT_CHARACTER_SET_NAME as Charset, DEFAULT_COLLATION_NAME as Collation
FROM information_schema.SCHEMATA
WHERE SCHEMA_NAME = 'youtarr';

-- Table Character Sets (excluding Sequelize metadata)
SELECT 'TABLE' as Object_Type, TABLE_NAME as Name,
IFNULL(CCSA.CHARACTER_SET_NAME, '') as Charset,
TABLE_COLLATION as Collation
FROM information_schema.tables t
LEFT JOIN information_schema.COLLATION_CHARACTER_SET_APPLICABILITY CCSA
ON t.TABLE_COLLATION = CCSA.COLLATION_NAME
WHERE TABLE_SCHEMA = 'youtarr'
AND TABLE_TYPE = 'BASE TABLE'
AND TABLE_NAME != 'SequelizeMeta'
ORDER BY TABLE_NAME;

It doesn't matter if the SequelizeMeta table is not utf8mb4

Solution Either:

  1. Recreate your DB with the correct character set (THIS WILL CAUSE LOSS OF ALL DB DATA) or
  2. Backup your DB and then convert your existing DB to the correct character set.
  ALTER DATABASE youtarr CHARACTER SET = utf8mb4 COLLATE = utf8mb4_unicode_ci;

Note: ALTER DATABASE only changes the default for new tables. Existing tables keep their old character set, so you'll need to convert each one too. See UTF8mb4 Migration Fails on Foreign Key Columns below for how (foreign key checks have to be off first).

UTF8mb4 Migration Fails on Foreign Key Columns​

Problem: On startup the 20250907000000-upgrade-to-utf8mb4-if-needed migration fails with logs like:

Upgrading database to utf8mb4...
Converting table JobVideos from utf8mb3_general_ci to utf8mb4_unicode_ci
UTF8mb4 migration failed: ...

It fails on an ALTER TABLE ... CONVERT TO CHARACTER SET for a table that has a job_id foreign key (JobVideos or JobVideoDownloads). This is almost always an external database that was created as utf8/utf8mb3 instead of utf8mb4.

Cause: The job_id columns are UUIDs stored as CHAR(36), and they're part of a foreign key into the Jobs table. MariaDB won't change the character set of a column that's part of a foreign key, so the conversion fails right there. It only happens when the database was created as utf8mb3 in the first place. The bundled MariaDB is created as utf8mb4, so it skips the conversion entirely and never runs into this.

Solution: Update Youtarr. The migration now turns foreign key checks off while it converts the tables and turns them back on afterward. It also checks each table on its own instead of trusting the database default, so it'll finish the job on a database that an earlier failed run left half-converted (database default already on utf8mb4, some tables still on utf8mb3).

To fix it by hand before updating, connect to the database as root and run the conversion with foreign key checks off. Replace youtarr with your database name, and add an ALTER TABLE line for every table that's still on utf8mb3:

SET FOREIGN_KEY_CHECKS = 0;
ALTER DATABASE youtarr CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
ALTER TABLE JobVideos CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
ALTER TABLE JobVideoDownloads CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
-- ... repeat for any other table still on utf8mb3 ...
SET FOREIGN_KEY_CHECKS = 1;

The character-set query in UTF-8 Character Errors above will tell you which tables are still on the wrong character set.

On MariaDB 10.4.31, 10.5.22, 10.6.15, 10.11.5, 11.x, 12.x and later, SET FOREIGN_KEY_CHECKS = 0 no longer permits this, and the CONVERT TO fails with Cannot change column 'job_id': used in a foreign key constraint. Drop the two job_id foreign keys first and recreate them afterward, exactly as in the manual recipe under Startup Fails with Illegal Mix of Collations.

Prevention: If you run your own database, create it as utf8mb4 from the start and this conversion never has to run. See the External Database Guide.

Startup Fails with Illegal Mix of Collations​

Problem: On startup a migration fails with:

Failed to initialize database
Illegal mix of collations (utf8mb4_general_ci,IMPLICIT) and (utf8mb4_unicode_ci,IMPLICIT) for operation '='

The first migration to hit it is 20260907174043-playlist-following-and-download-dates, and the UI shows the "Database Schema Mismatch" overlay.

Cause: The database has tables on two different collations. A database that was already utf8mb4 when the September 2025 upgrade migration ran was skipped entirely (that version only checked the database default charset), so its original tables stayed on utf8mb4_general_ci, or even three-byte utf8. Tables created since then use an explicit utf8mb4_unicode_ci. MariaDB and MySQL refuse to compare string columns across the two, and the playlist following migration is the first to join videos to playlistvideos in SQL.

Solution: Update Youtarr. The 20260907000000-normalize-utf8mb4-unicode-collation migration converts every table and the database default to utf8mb4_unicode_ci before the playlist migration runs, and restores utf8mb4_bin on the UUID foreign key columns that the conversion coerces. It is safe to re-run and changes collations only, never data. Expect it to take a while on large videos and channelvideos tables, since each conversion rebuilds the table.

To fix it by hand instead, take a backup, connect as root, and run the following with youtarr replaced by your database name, the two constraint names filled in from the second query, and one ALTER TABLE ... CONVERT TO line per table the first query lists. Before dropping the constraints, record their names and update/delete rules from the second query so you can preserve those rules when recreating them:

-- Which tables are off
SELECT TABLE_NAME, TABLE_COLLATION FROM information_schema.tables
WHERE TABLE_SCHEMA = DATABASE() AND TABLE_TYPE = 'BASE TABLE'
AND TABLE_COLLATION <> 'utf8mb4_unicode_ci';
-- The two job_id foreign keys (their names differ between installs)
SELECT TABLE_NAME, CONSTRAINT_NAME, UPDATE_RULE, DELETE_RULE
FROM information_schema.REFERENTIAL_CONSTRAINTS
WHERE CONSTRAINT_SCHEMA = DATABASE() AND REFERENCED_TABLE_NAME = 'jobs';

SET FOREIGN_KEY_CHECKS = 0;
ALTER TABLE jobvideos DROP FOREIGN KEY `<jobvideos constraint name>`;
ALTER TABLE jobvideodownloads DROP FOREIGN KEY `<jobvideodownloads constraint name>`;
ALTER DATABASE youtarr CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
ALTER TABLE videos CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
-- ... one line per table from the first query ...
ALTER TABLE jobs MODIFY id CHAR(36) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL;
ALTER TABLE jobvideos MODIFY job_id CHAR(36) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL;
ALTER TABLE jobvideodownloads MODIFY job_id CHAR(36) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL;
ALTER TABLE jobvideos ADD CONSTRAINT jobvideos_job_id_fk
FOREIGN KEY (job_id) REFERENCES jobs (id) ON UPDATE CASCADE;
ALTER TABLE jobvideodownloads ADD CONSTRAINT jobvideodownloads_job_id_fk
FOREIGN KEY (job_id) REFERENCES jobs (id) ON UPDATE CASCADE ON DELETE CASCADE;
SET FOREIGN_KEY_CHECKS = 1;

The ADD CONSTRAINT lines match the rules the migrations originally created (no ON DELETE clause on jobvideos, ON DELETE CASCADE on jobvideodownloads); if the second query showed different rules for your database, keep yours. The three MODIFY lines are required: CONVERT TO changes the UUID key columns to utf8mb4_unicode_ci, and the jobvideos foreign key stops working until they are back on utf8mb4_bin. The foreign keys have to come off before the conversion and go back after it: MariaDB 10.4.31, 10.5.22, 10.6.15, 10.11.5, 11.x, 12.x and later refuse to change the collation of a foreign key column even with FOREIGN_KEY_CHECKS = 0. Restart Youtarr afterward and the pending migrations complete.

Collation Migration Fails with "Cannot change column 'job_id'"​

Problem: On startup the 20260907000000-normalize-utf8mb4-unicode-collation migration fails with:

Cannot change column 'job_id': used in a foreign key constraint 'JobVideoDownloads_ibfk_1'
ALTER TABLE `jobvideodownloads` CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci

or the same message for jobs.id (Cannot change column 'id': used in a foreign key constraint ...), and the UI shows the "Database Issue Detected" overlay. The bundled MariaDB 10.3 is not affected; this appears on external or platform-managed databases running MariaDB 10.4.31, 10.5.22, 10.6.15, 10.11.5, 11.x, 12.x or later.

Cause: Those MariaDB releases (MDEV-31086) refuse to change the character set or collation of a column that takes part in a foreign key, even with FOREIGN_KEY_CHECKS = 0. The first release of the normalization migration relied on that setting to convert the jobs, jobvideos and jobvideodownloads tables in place.

Solution: Update Youtarr. The migration now reads the foreign keys on the jobs UUID chain from information_schema, drops them before converting, and recreates them with their original names and rules once the UUID columns are back on utf8mb4_bin. Because the migration never got recorded, it re-runs on the next start and picks up where it stopped: tables it already converted are left alone. The manual recipe in the previous section works on every supported MariaDB and MySQL release if you need the instance back before updating.

Migration Fails Creating JobVideoDownloads (errno 150)​

Problem: A fresh install (or an upgrade of an older install) fails partway through migrations with:

Can't create table `youtarr`.`JobVideoDownloads` (errno: 150 "Foreign key constraint is incorrectly formed")

and the server starts in degraded mode.

Cause: This happens when the database was not created with utf8mb4 defaults - an external database, or a MariaDB service running without the compose file's --character-set-server=utf8mb4 arguments. The Jobs.id and JobVideos.job_id columns are UUIDs stored as CHAR(36) with the binary collation utf8mb4_bin. When the utf8mb4 conversion above runs, ALTER TABLE ... CONVERT TO CHARACTER SET coerces them to utf8mb4_unicode_ci. The JobVideoDownloads migration then creates its job_id column as utf8mb4_bin, and InnoDB refuses the foreign key because the collations on the two sides no longer match.

Solution: Update Youtarr. The migrations now restore the binary collation automatically - the utf8mb4 conversion re-applies it right after converting, and the JobVideoDownloads migration repairs it before creating the table, so a restart on the latest image finishes the job.

To fix it by hand instead, connect to the database as root and run:

SET FOREIGN_KEY_CHECKS = 0;
ALTER TABLE Jobs MODIFY id CHAR(36) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL;
ALTER TABLE JobVideos MODIFY job_id CHAR(36) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL;
SET FOREIGN_KEY_CHECKS = 1;

then restart the Youtarr container; the remaining migrations will complete.

Prevention: Same as the previous section - create your own database as utf8mb4 from the start, or keep the charset arguments from the bundled docker-compose.yml.

Database Connection Failed​

Problem: Cannot connect to database errors.

Solution:

  1. Ensure the database container is running (the commands below only applies if using the bundled DB):

    docker ps | grep youtarr-db
  2. Check database logs:

    docker logs youtarr-db
  3. Verify database credentials in environment

Stuck on "Waiting for database"​

Problem: The youtarr container loops Waiting for database... (attempt N/30) and finally exits with Failed to connect to database after 30 attempts, with no other error in its logs.

Cause: Usually a credentials mismatch that stays silent because the startup wait loop only reports that the connection failed, not why. A common one when connecting as root: DB_ROOT_PASSWORD sets the bundled MariaDB's root password, while the app connects using DB_PASSWORD. Both default to the same value, so setting only one of them in .env makes the two sides disagree and the app can never log in.

Solution: When connecting as root, set DB_ROOT_PASSWORD and DB_PASSWORD to the same value in .env (or set neither). If the database volume was already initialized with a different root password, either use that password or wipe the database directory and let it re-initialize (this deletes all DB data). docker logs youtarr-db will show Access denied warnings when it's a credentials problem.

MariaDB only reads its password settings the first time it starts with empty storage, so changing them later has no effect on an existing database. This often catches Portainer users: deleting and re-creating a stack keeps its database volume, so the old password is still in place. See Changing the database password in the Portainer guide.

Database Empty After a Reboot or Redeploy​

Problem: After a server reboot, re-creating a stack, or moving Youtarr to a new folder, your channels and download history are gone. Some videos may still be listed: when the config folder survives, Youtarr refills up to 300 recent videos from its download record (config/complete.list) on startup, so the Videos page can look partly filled while the Channels page is empty.

Cause: Youtarr started on a new, empty database because the database storage it used before is no longer the one mounted. Common ways this happens:

  • A stack manager with the repository's compose file. Portainer and similar tools run each stack from their own folder, so ./database lives somewhere like /data/compose/<stack id>/database on the host. A re-created stack gets a new ID and a new, empty folder. On Unraid, that folder is in memory and is wiped on reboot.
  • A renamed folder or stack with a named volume. Docker Compose names the youtarr-db-data volume after the project (usually the folder or stack name), for example youtarr_youtarr-db-data. A new name gives you a new, empty volume.
  • A database folder copied into the wrong place, for example ending up at database/database.

To see where the current database is stored:

docker inspect youtarr-db --format '{{range .Mounts}}{{if .Name}}{{.Name}}{{else}}{{.Source}}{{end}}{{end}}'

To see when the current database was created (a date matching the day your data disappeared means Youtarr started from scratch then):

docker exec youtarr-db sh -c 'exec mysql -uroot -p"$MYSQL_ROOT_PASSWORD" youtarr -e "SELECT MIN(migration_date) AS created FROM _charset_migration_log"'

Solution:

  1. Look for the old database before changing anything: an older volume in docker volume ls, the old ./database folder, or, for Portainer, the other folders in /data/compose/. If you find it, point the stack back at it (the Portainer guide shows how to move it to a permanent place).
  2. If it's gone, restore from a backup if you have one (see Backup and Restore).
  3. Otherwise, re-add your channels. As long as config/complete.list survived, Youtarr won't download videos it already downloaded.

Prevention: Store the database at a fixed, absolute path or in a volume with a fixed name:, and back it up. Portainer users should use the stack in the Portainer guide.

Access Denied for Custom Database User​

Problem: After changing DB_USER and DB_PASSWORD in your .env file to use a non-root user, you see access denied errors in the logs:

youtarr-db  | 2025-11-22  6:28:19 8 [Warning] Access denied for user '<DB_USER>'@'172.25.0.3' (using password: YES)

Cause: When using the bundled MariaDB container, you changed DB_USER and DB_PASSWORD in .env but forgot to uncomment the corresponding MYSQL_USER and MYSQL_PASSWORD environment variables in docker-compose.yml. MariaDB needs these variables to create the custom user during initialization.

Solution:

  1. Stop Youtarr: ./stop.sh or docker compose down

  2. Edit docker-compose.yml and uncomment the MYSQL_USER and MYSQL_PASSWORD lines under the youtarr-db service:

    environment:
    MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
    MYSQL_DATABASE: ${DB_NAME}
    MYSQL_USER: ${DB_USER} # Uncomment this line
    MYSQL_PASSWORD: ${DB_PASSWORD} # Uncomment this line
  3. If the database has already been initialized with incorrect credentials, remove the database directory:

    WARNING: This will completely remove your DB data!

    docker compose down
    rm -rf ./database
    # Or if using a named volume. Compose prefixes the name with the project name,
    # usually youtarr_youtarr-db-data; confirm with: docker volume ls | grep youtarr-db-data
    docker volume rm youtarr_youtarr-db-data
  4. Start Youtarr again: ./start.sh or docker compose up -d

Note: This only applies when using the bundled MariaDB container. External database setups don't need the MYSQL_USER/MYSQL_PASSWORD variables.

MariaDB init: Operation CREATE USER failed for 'root'@'%'​

Problem: Fresh installs that only use .env + docker-compose.yml fail during the MariaDB bootstrap with:

ERROR 1396 (HY000) at line 21: Operation CREATE USER failed for 'root'@'%'

Cause: The compose file was configured to set MYSQL_USER=root. MariaDB already creates the root accounts internally, so trying to create it again aborts initialization and leaves the builtin tables in a crashed state.

Solution:

  1. Leave the MYSQL_USER / MYSQL_PASSWORD lines commented out in docker-compose.yml when DB_USER=root (the default). Only uncomment them if you explicitly set a non-root DB_USER / DB_PASSWORD in .env.
  2. Stop the stack with docker compose down, then remove the broken datadir: rm -rf ./database for a bind mount, or docker volume rm youtarr_youtarr-db-data for a named volume. Compose prefixes the volume with the project name, so confirm yours with docker volume ls | grep youtarr-db-data.
  3. Run docker compose up -d again. MariaDB will initialize cleanly.

Duplicate Column Errors After Upgrade​

Problem: MariaDB logs Duplicate column name 'duration' (or similar) when the stack starts. The API returns Database error: Duplicate column name ....

Cause: The SequelizeMeta table was lost or corrupted, so Sequelize re-ran migrations on top of a populated schema. Every migration now checks for existing tables/columns/indexes before mutating anything, so simply restarting the containers lets the stack skip duplicate work automatically in most cases. NOTE: This should not happen anymore, migrations have been updated to be idempotent.

Solution:

  1. Restart the stack (docker compose up -d). If the schema had already been migrated, the rerun will now skip those operations.
  2. If the error persists, check docker compose logs youtarr to see which migration is still failing.
  3. Manually reconcile the schema for that migration:
    • Connect to MariaDB: docker compose exec youtarr-db mysql -u root -p youtarr
    • Drop the duplicate column or table mentioned in the error (for example ALTER TABLE videos DROP COLUMN media_type;), or restore a known-good backup.
    • Exit MySQL and restart the stack.
  4. Once the stack is back online, confirm the schema is healthy: curl http://localhost:3087/api/db-status reports whether the database connection and schema checks passed, and the startup logs (docker compose logs youtarr) show the migration results.

Tip: run with a named volume (see Docker Desktop/ARM/Synology sections) so filesystem corruption is less likely to recur.

Docker Desktop / ARM: Incorrect information in file errors​

Problem: MariaDB logs errors like:

ERROR 1033 (HY000): Incorrect information in file: './youtarr/videos.frm'

or:

errno 1932 - Table 'youtarr.videos' doesn't exist in engine

This can happen when MariaDB data lives on the bind-mounted host directory (./database:/var/lib/mysql) and Docker proxies that directory through a virtualized filesystem, most often Docker Desktop on Windows/macOS, ARM hosts, or some NAS setups. During DDL operations such as CREATE TABLE or ALTER TABLE, InnoDB can end up out of sync with MariaDB's table metadata. Native Linux Docker hosts are usually unaffected.

Existing install with data to preserve

Use the migration helper. It dumps the bind-mounted DB, preserves ./database/ as a timestamped backup directory, pins the named-volume override in .env, and imports the dump into a fresh named-volume MariaDB:

./scripts/migrate-to-named-volume.sh

See Database Management for the full migration and revert details.

Fresh install with no data to preserve

Start with the named-volume override:

docker compose -f docker-compose.yml -f docker-compose.arm.yml up -d

Or add this to .env before plain docker compose up -d:

COMPOSE_PATH_SEPARATOR=:
COMPOSE_FILE=docker-compose.yml:docker-compose.arm.yml

Alternatives:

  • Point Youtarr at an external MariaDB/MySQL instance via ./start-with-external-db.sh.
  • Run the stack on Linux/WSL, which uses a native filesystem for bind mounts.

Download Issues​

Videos Not Downloading​

Problem: Channels are added but videos aren't downloading.

Checklist:

  1. Check the download directory is correctly configured
  2. Verify the directory is accessible by Docker
  3. Check logs for yt-dlp errors:
    docker compose logs -f youtarr | grep yt-dlp
  4. Ensure the cron schedule is configured (default: hourly)
  5. Open Settings -> Scheduling and check the Automatic downloads card: it shows the next run, the last run and its result, and its Run now button starts a check immediately; you can also manually trigger a download with Download new under Downloads -> Manual Download.

yt-dlp Errors​

Problem: yt-dlp fails to download videos.

Solution #1:

Update yt-dlp. Most download failures are extractor breakage that a newer yt-dlp fixes.

  • The fastest fix is in-app: go to Settings -> YT-DLP and update yt-dlp manually. With Automatically update yt-dlp enabled, this happens on the schedule configured in Settings -> Scheduling (daily at 04:00 by default).
  • If the latest stable yt-dlp still fails, switch the Update Channel to Nightly on the same page. Nightly gets extractor fixes days earlier than stable.
  • Youtarr's Docker image also bundles the latest yt-dlp at release time, so pulling a new image updates it too:
    • Via docker compose:
      docker compose down
      docker compose pull
      docker compose up -d
    • Using helper scripts:
      ./stop.sh
      ./start.sh --pull-latest

Solution #2:

YouTube is blocking your downloads.

  1. If cookies are not enabled, try enabling and uploading cookies in Settings -> Cookies. If cookies are enabled, they may be the cause - see "Downloads Fail with HTTP 403" below.
  2. If only some videos are failing, try increasing the Sleep Between Requests (seconds) value in the yt-dlp Options section of Settings -> YT-DLP
  3. Try using a proxy, or switching to a VPN

NOTE: In some cases YouTube may temporarily blacklist your IP address if too many requests were happening from your IP. You may just need to wait in order to download again. You can manually test downloading a video from YouTube to rule out Youtarr-specific issues by downloading yt-dlp and attempting to manually download a single video.

Downloads Fail with HTTP 403: Forbidden​

Problem: A video (or every video) fails with unable to download video data: HTTP Error 403: Forbidden, even after Youtarr's automatic retry. Metadata, thumbnails, and subtitles often download fine; only the video itself fails.

Youtarr detects this pattern and shows a "Likely cause" diagnosis on the Downloads page, in Download History (expand the failed job's row), and in notifications. The right fix depends on whether cookies are enabled:

If cookies are enabled (Settings -> Cookies):

Uploaded cookies change which YouTube player client yt-dlp can use, and YouTube enforces stricter requirements on that path. Stale or rotated cookies are the most common trigger - YouTube rotates cookie values regularly, so an exported cookies file goes invalid over time.

  1. Refresh your cookies first: sign into YouTube in your browser, re-export cookies with a browser extension (e.g., "Get cookies.txt LOCALLY"), and upload the fresh file. Refreshing preserves whatever you enabled cookies for. Test cookies in Settings -> Cookies confirms whether the current file is still signed in.
  2. If fresh cookies still fail, temporarily disable cookies and retry the video. Many videos download fine without cookies because yt-dlp can then use a less restricted client.

If cookies are not enabled:

The 403 is sometimes a temporary block on YouTube's side - retrying later can work. If it keeps failing, uploading YouTube cookies from your browser (Settings -> Cookies) often resolves it.

Note: The same failure on one machine but not another usually comes down to this cookies difference, not the network - both machines can share an IP and behave differently.

Test Cookies Says Not Signed In​

Problem: Settings -> Cookies -> Test cookies reports that YouTube did not recognize a signed-in session.

The cookie file no longer belongs to a signed-in YouTube session. The cookies expired, YouTube rotated them (it does this regularly, and signing out or exporting from a browser that then keeps using the session can invalidate the exported copy), or they were exported from a signed-out browser. The details above the button may also show expired login cookies or none at all.

  1. Sign into YouTube in your browser (ideally a private window you close right after exporting, so the browser does not rotate the exported session).
  2. Re-export cookies with a browser extension (e.g., "Get cookies.txt LOCALLY").
  3. Upload the fresh file (or replace your YOUTARR_COOKIES_FILE source) and run Test cookies again.

If the test reports a bot check instead, sign into YouTube in your browser, solve any challenge it shows, then re-export. A network or timeout failure means YouTube could not be reached; check the server's internet connection and the proxy setting in Settings.

Downloads Are Only 360p With Cookies Enabled​

Problem: With cookies enabled, videos download at 360p (yt-dlp logs Downloading 1 format(s): 18) even though the video is available in HD, and the video details modal lists 360p as the only available resolution. Disabling cookies brings HD back.

This is a YouTube-side change, not stale cookies. With logged-in cookies, yt-dlp uses a different set of YouTube player clients, and YouTube has been moving those clients to "SABR-only" streaming on a per-account basis (tracked upstream in yt-dlp issues 12482 and 17666). For an affected account the logged-in clients return stream formats with no download URL, so the only stream left is the old progressive 360p one. The logs show Some ... client https formats have been skipped as they are missing a URL. YouTube may have enabled the SABR-only streaming experiment for your account.

Youtarr works around this by asking yt-dlp for two additional player clients whenever cookies are enabled (mweb and web_safari, on top of yt-dlp's defaults), and shows a "SABR-only" warning on the Downloads page when YouTube strips formats for your account. What you get then depends on the account:

  • YouTube Premium account: full-quality separate video and audio streams, same as without cookies.
  • Free account: the HLS stream, which tops out at 1080p (H.264 with AAC audio). YouTube requires a Proof-of-Origin token for the higher-quality streams on free logged-in sessions, which Youtarr does not currently generate.

If you only enabled cookies to get past a "Sign in to confirm you're not a bot" check, try disabling them (Settings -> Cookies) and see whether downloads still work; without cookies yt-dlp uses a client that is not affected. If you need cookies and want more than 1080p on a free account, the upstream SABR downloader (yt-dlp pull request 13515) is the eventual fix.

Note: If you use a throwaway Google account for cookies, sign into it from a normal browser occasionally. Accounts used only from a server IP have been disabled by Google.

Subtitle Downloads Time Out​

Problem: With subtitles enabled, downloads log [download] Got error: HTTPSConnectionPool(host='www.youtube.com', port=443): Read timed out right after Writing video subtitles to: ..., and each affected video takes a couple of extra minutes.

This is the subtitle request (YouTube's timedtext endpoint), not the video: video streams come from googlevideo.com. YouTube throttles or hangs subtitle requests that don't look like they come from a browser, so yt-dlp sends them with browser impersonation, which needs the curl_cffi library. Youtarr's Docker image includes it; if you see WARNING: The extractor specified to use impersonation for this download, but no impersonate target is available in the logs, you are on an older image and should pull the latest.

Even with impersonation, YouTube's subtitle endpoint is flaky at times. When the subtitle fetch fails, yt-dlp still downloads the video; Youtarr keeps the video, does not count it as a failed download, and marks the job "Complete with Warnings". The same applies when YouTube sends back an empty subtitle file, which logs ERROR: Did not get any data blocks after Writing video subtitles to: .... If the extra retry time bothers you, disable subtitles in Settings -> Core until it settles.

SponsorBlock Lookup Fails​

If a download logs ERROR: Unable to communicate with SponsorBlock API, the video can still download successfully without SponsorBlock segment processing. Youtarr keeps successfully downloaded videos in the archive and marks the job "Complete with Warnings", and the download's completion message says how many videos couldn't reach SponsorBlock. A failed SponsorBlock lookup alone does not cause the video to be downloaded again on the next run.

An error starting with Preprocessing: Unable to communicate with SponsorBlock API still counts as a video failure because yt-dlp abandons that video. Other video download failures are also reported normally.

Downloads Fail with "Conversion failed!" or "No space left on device"​

Problem: A video (usually a large one) downloads completely and then fails with Conversion failed!, or a job stops with Out of disk space in the temporary folder. If the disk is completely full you may also see every list in the app come up empty (no channels, no videos) until space is freed.

Conversion failed! is what ffmpeg reports when it cannot write the merged file. Merging the video and audio streams needs a second copy of the video, so the folder downloads are staged in needs free space of about twice the video's size. When Youtarr measures that this is what happened, the failed job shows a "Not enough disk space to finish the download" diagnosis (Downloads page, Download History, and notifications) and the log has a Download failed because the temporary download folder is out of space line with the folder and its free space. Youtarr normally removes the failed video's leftover files when that download run ends, so the space comes back on its own; anything left is cleared when the next download job starts.

Which disk is full depends on External temp directory (Settings -> Core -> Advanced):

  • Off (default): downloads are staged in .youtarr_tmp/ inside your output folder, so your media drive is the one that is short on space.
  • On: downloads are staged inside the container (/tmp/youtarr-downloads unless you changed it). Unless you mounted a volume there, this is Docker's own storage. On Docker Desktop (Windows/macOS) that is a virtual disk with a fixed maximum size, shared with every image, the build cache, and every other container; free space on your drives does not count.

To check: look at free space on the folder downloads are staged in, as the container sees it. The log line above names that folder (tempPath); use it if you changed the output or temp path.

# Setting off (default): staging is under the output folder
docker exec youtarr df -h /usr/src/app/data

# Setting on: staging is the external temp path
docker exec youtarr df -h /tmp/youtarr-downloads

To fix:

  • Your media drive is full (setting off, or a volume you mounted at the external temp path): free up space on that drive.

  • Docker's own storage is full (setting on, nothing mounted at the external temp path): see what is using it and reclaim what you do not need:

    # What is using Docker's disk
    docker system df

    # Reclaim build cache, then images no container uses
    docker builder prune
    docker image prune -a

If large videos regularly do not fit in the external temp path, mount a volume with enough room there, or turn External temp directory off so staging uses your output drive (some managed platforms, such as ElfHosted, choose the staging location for you).

A channel video that failed this way is retried by each scheduled download for as long as it is still among the most recent videos the check looks at (Videos per channel tab and playlist, Settings -> Core -> Downloads) and passes the channel's filters, so it normally completes once there is room. If it has dropped out of that window, download it manually.

No Download Progress Shown (Downloads Work, Videos "Just Appear")​

Problem: Downloads complete successfully, but the Downloads -> Activity page never updates live: progress percentages stay frozen (or the page shows "Waiting for progress updates...") until you refresh the page or switch back to the tab. Other real-time updates (channel refresh status, download complete notifications) are also missing.

Cause: Youtarr delivers all real-time updates over a WebSocket connection that shares the same host and port as the web UI. Regular page loads and downloads use plain HTTP, so everything else works - but if something between your browser and Youtarr (most commonly a reverse proxy) doesn't forward WebSocket upgrade requests, the progress display never gets live updates.

How to confirm:

  1. Open your browser devtools (F12) -> Network tab -> filter by "WS", then reload the Youtarr page. A working setup shows a WebSocket connection with status 101 Switching Protocols. A 401 status means the connection reached Youtarr but was refused because the page has no valid login: reload the page (a tab left open across an upgrade still runs the old page) or log in again. If it fails in any other way or keeps retrying, the WebSocket is being blocked.
  2. While a download is running, watch the Activity page. It seeds its state over plain HTTP, so it will show the running job and catch up whenever you refresh or refocus the tab - but live progress between refreshes only arrives over the WebSocket. If the page stays frozen until you refresh, the WebSocket is the problem.

Solution: Enable WebSocket support for the Youtarr host in your reverse proxy:

  • Nginx Proxy Manager: edit the proxy host and enable the Websockets Support toggle.
  • nginx: add to the Youtarr location block:
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
  • Synology DSM reverse proxy: open the reverse proxy rule -> Custom Header -> Create -> WebSocket (adds the Upgrade and Connection headers).
  • Apache: enable mod_proxy_wstunnel.
  • Caddy / Traefik: WebSocket pass-through is automatic; no configuration needed.

If you aren't using a reverse proxy, check for browser extensions, VPN software, or corporate proxies that block WebSocket connections.

Slow Channel Operations with Proxy​

Adding or Refreshing Channels Takes ~15 Seconds​

Problem: Adding a new channel or refreshing channel metadata takes around 15 seconds longer than expected.

Cause: Youtarr first attempts direct HTTP requests for thumbnails and RSS feeds. When you're using a SOCKS5 or HTTP proxy, these direct requests cannot reach YouTube and must wait for a 15-second timeout before falling back to yt-dlp, which correctly uses your configured proxy.

Solution: This is expected behavior and no action is needed. The operations will complete successfully after the brief timeout. If operations are taking significantly longer than 15-20 seconds, verify your proxy is correctly configured in Configuration > Advanced Settings.


Plex Integration Issues​

Videos Not Showing in Plex​

Problem: Downloaded videos don't appear in Plex library.

Checklist:

  1. Verify Plex library is set to "Other Videos" type
  2. Ensure Plex agent is "Personal Media"
  3. Check Plex has access to the download directory
  4. Manually scan the library in Plex
  5. Verify Plex server IP and port are correct
    • Docker Desktop (Windows/macOS): host.docker.internal
    • Docker on macOS without Docker Desktop (e.g., Colima): host LAN IP (e.g., 192.168.x.x) or host.lima.internal
    • Docker on Linux or running inside WSL2 without Docker Desktop: host LAN IP (e.g., 192.168.x.x)
    • Ensure the Plex Port matches your Plex configuration (default 32400).

Cannot Connect to Plex​

Problem: Youtarr cannot communicate with Plex server.

Solution:

  1. Verify the Plex IP and port settings:
  • Docker Desktop (Windows/macOS): use host.docker.internal
  • Docker on macOS without Docker Desktop (e.g., Colima): use the host LAN IP (e.g., 192.168.x.x) or host.lima.internal
  • Docker on Linux or running inside WSL2 without Docker Desktop: use the host LAN IP (e.g., 192.168.x.x)
  • Update the Plex Port field if Plex listens on a non-default port (default 32400).
  1. Ensure Plex is running on the same machine
  2. Check firewall isn't blocking local connections
  3. Verify Plex is accessible at the configured IP and port

Playlist Sync Issues​

For how playlist sync works across Plex, Jellyfin, and Emby, see Media Server Playlists. The most common issues:

Videos Missing from a Synced Playlist​

Problem: A playlist syncs, but some videos aren't in it.

Checklist:

  1. Confirm the videos are actually downloaded. Youtarr only adds videos that exist on disk; a video still showing as "Tracked" on the playlist page hasn't downloaded yet.
  2. A video has to be indexed in your media server's library before it can be added. Trigger a library scan and use Sync now on the playlist page.
  3. Check that the video isn't marked Ignored on the playlist page.
  4. Check the item's format matches the playlist's Download Type: an MP3 Only playlist syncs only items that have an mp3, and a video playlist syncs only items with a video file, so items downloaded in the other format (for example via a per-video override) are left out. The playlist page shows a notice with the count of affected items; see Switching a playlist's download type.

Playlist Not Created on Jellyfin or Emby​

Problem: You enabled sync but no native playlist appears.

Checklist:

  1. Open Settings -> Jellyfin Integration (or Settings -> Emby Integration) and click Test Connection. A stale API key or changed server URL is the usual cause.
  2. Confirm the configured User still exists on the server.
  3. Youtarr won't create the playlist until at least one of its videos is downloaded and indexed. Download a video, then Sync now.

Playlist Not Visible to Other Users (Plex)​

This is by design. Plex playlists are owned by a single account, and Youtarr can't grant per-user access. To share one, open the playlist in Plex Web and share it (playlist menu -> Share), or use Settings -> Manage Library Access -> [user] -> Media to grant playlists to a user. See the Plex playlist visibility scope notes for unclaimed-server setups.

Shared Playlists Don't Appear for Other Users (Plex)​

Problem: You shared a Youtarr-created playlist with another Plex user (the share shows up correctly under Settings -> Manage Library Access -> [user] -> Media), but when that user opens the server's Playlists section it says "Playlists is empty" - on every client (Web, iOS, Apple TV, etc.).

This is Plex behavior, not a Youtarr bug, and nothing needs to be reconfigured. In Plex, the Playlists source only lists playlists the user created themselves. Playlists shared by another account appear under a separate sidebar source named Media, at the same level as Playlists and Libraries. Have the recipient open Media in the server's sidebar; the shared playlists are listed there.

Related gotchas when sharing playlists with other users:

  1. Sharing a playlist does not grant access to the underlying library. The recipient also needs the Youtarr library shared with them, or the playlist's items will be hidden.
  2. Content-rating restrictions hide YouTube videos. Downloaded YouTube videos have no content rating, so rating-based parental restrictions filter them out. For kid accounts, use label-based restrictions instead.
  3. Smart playlists can't be shared - but Youtarr creates standard playlists, so this doesn't affect Youtarr-created playlists.

Watch Status Issues​

Videos Not Showing as Watched​

Problem: You've watched videos on your media server, but Youtarr never shows the Watched chip for them.

Solutions:

  1. Confirm the sync is on and has run: open Settings -> Watch Status, click Sync Now, and check the per-server results for the last run. A server that errors here is usually a connection or API-key problem; fix that first.
  2. Watching in Youtarr's built-in player doesn't count. Watch status only comes from your media servers.
  3. All three servers only mark a video played once playback passes a configurable percentage threshold (90% by default), so a video you stopped partway through may genuinely not count as watched yet. See What determines if a video is "watched" for where to change the threshold on each server.
  4. Check for a path mismatch. Youtarr matches watch state to videos by filename, so if the server is indexing files from a different copy of your library (or files renamed to drop the [<youtube-id>] segment), nothing will match. Run a rescan if you've moved or renamed files.
  5. For non-owner Plex users specifically: their state comes from the server's play history, and that pull is incremental. If a path mismatch prevented matching for a while, plays from that period may have been scanned already and won't be picked up on later syncs. After fixing the mismatch, delete the plex row from the watch_status_sync_cursors table to force a full history re-scan on the next sync (see the Configuration Reference).

Channel Import Issues​

Cookies Upload Fails or Returns No Channels​

Problem: Uploading a cookies file returns an error, or YouTube reports no subscriptions for the account.

Common causes and solutions:

  1. Expired or invalid cookies: Cookies from YouTube sessions expire. If you see "cookies appear to be expired or invalid," sign into YouTube in your browser, re-export your cookies using a browser extension (e.g., "Get cookies.txt LOCALLY"), and upload the fresh file.

  2. Wrong file format: The cookies file must be in Netscape cookies.txt format (the first line starts with # Netscape HTTP Cookie File). If you copied cookies from browser dev tools or exported in a different format, the upload will be rejected. Use a browser extension that exports in the Netscape format.

  3. Not logged into the right YouTube account: If the upload succeeds but returns zero channels, the cookies may belong to an account with no subscriptions. Make sure you are signed into the correct YouTube account before exporting cookies.

  4. Bot detection / verification challenge: YouTube sometimes flags automated access and shows a CAPTCHA or verification prompt. If you see "YouTube is asking for verification," open YouTube in your browser using the same account, complete any security challenges, then re-export your cookies and try again.

CSV Upload Errors​

Problem: Uploading a CSV file returns "Missing header" or another parsing error.

Common causes and solutions:

  1. Wrong file: The import expects the subscriptions.csv file from Google Takeout, which has exactly three columns: Channel Id, Channel Url, Channel Title. If you uploaded a different CSV (e.g., a watch history or playlist export), select the correct file from your Takeout archive under YouTube and YouTube Music/subscriptions/subscriptions.csv.

  2. File too large: CSV uploads are limited to 5 MB. A typical Takeout subscriptions file is well under this limit. If your file exceeds it, verify you selected the right file; the subscriptions CSV should not be that large.

  3. Encoding issues: The parser expects UTF-8 encoding and handles a UTF-8 BOM if present. If your CSV was re-saved in a different encoding (e.g., UTF-16 or Latin-1), re-export from Google Takeout or re-save as UTF-8 in a text editor before uploading.

  4. No valid channels found: If the file parses but contains no rows with valid YouTube channel IDs (IDs starting with "UC"), the CSV may have been modified or corrupted. Download a fresh copy from Google Takeout.

Individual Channels Fail During Import​

Problem: Some channels show errors during import while others succeed.

Per-channel failures are normal and do not stop the overall import. The import processes each channel independently and records individual results. Common reasons a single channel may fail:

  1. Bot detection / rate limiting: YouTube may throttle or block requests when many channels are resolved in sequence. Failed channels are marked with their error, and you can retry them later by running another import.

  2. Private or terminated channels: Channels that have been made private, deleted, or terminated by YouTube will fail with a lookup error. These cannot be imported.

  3. Network timeouts: Transient network issues can cause individual channel lookups to fail. Check the per-channel status on the import progress page; channels that failed due to temporary errors can be retried in a subsequent import.

Import Appears Stuck​

Problem: The import has been running for a long time with no visible progress.

Large imports take time because each channel requires a yt-dlp lookup to resolve metadata (name, thumbnail, video feed URL). An import of several hundred channels can take 10-30 minutes depending on network speed and YouTube's response times.

What to check:

  1. Open the import progress page to see per-channel status. If channels are still being processed, the import is working normally.
  2. Check the container logs for errors: docker compose logs -f youtarr
  3. If the import is truly unresponsive (no channels have progressed for several minutes), you can cancel it from the progress page and start a new one.

"Too Many Requests" Error​

Problem: The cookies upload endpoint returns a 429 "Too many requests" error.

The cookies preview endpoint is rate-limited to 3 requests per minute because each request runs a yt-dlp process against YouTube. Wait at least one minute before retrying. If you need to test multiple cookies files, space your uploads about 20-30 seconds apart.

Performance Issues​

High Memory/CPU Usage​

Problem: Youtarr consuming excessive resources.

Solution:

  1. Check for stuck download jobs (these can be cleared by restarting Youtarr)
  2. Restart containers:
    ./stop.sh
    ./start.sh
  3. Check disk space - low space can cause performance issues

Network Access Issues​

Cannot Access from Other Devices​

Problem: Can't access Youtarr from other computers on the network.

Solution:

  1. Configure firewall to allow port 3087
  2. Use server's actual IP address, not localhost
  3. Check Windows Defender Firewall settings
  4. Verify router settings if accessing from different subnet

Metadata Issues​

Metadata Not Showing in Media Server​

Problem: Videos play but metadata (title, description, etc.) isn't displaying in your media server.

Plex​

Solution:

  • Ensure "Local Media Assets" is enabled in your library agent settings
  • Place Local Media Assets at the top of the agent priority list
  • Check container logs for "Successfully added additional metadata to video file"
  • Try "Refresh Metadata" on the library or individual items
  • Verify the library type is "Other Videos" with "Personal Media" agent

Kodi/Jellyfin/Emby​

Solution:

  • Verify .nfo files exist alongside video files (same name, different extension)
  • Ensure library is configured as "Movies" or "Mixed" type
  • Enable "Nfo" metadata reader in library settings
  • Disable all online metadata scrapers to avoid conflicts
  • Try a full library rescan
  • Check file permissions - media server must be able to read .nfo files

Channel Posters Not Displaying​

Problem: Channel folders don't show artwork/posters. NOTE: Plex does not support channel posters, this is only supported on Kodi/Jellyfin/Emby

Solution:

  • Verify poster.jpg exists in each channel folder
  • Check that Channel poster.jpg is enabled in Settings -> Core -> Media server files
  • Ensure media server has read permissions for image files
  • Some servers cache artwork - try:
    • Clearing server cache
    • Restarting the media server
    • Removing and re-adding the library

Special Characters in Titles/Metadata​

Problem: Titles with $, &, or other special characters display incorrectly.

Solution:

  • Youtarr properly escapes XML characters in NFO files
  • For Plex: Embedded metadata handles special characters automatically
  • If issues persist:
    • Check media server logs for XML parsing errors
    • Verify you're running the latest version of Youtarr
    • Report specific character issues on GitHub

NFO Files Not Being Created​

Problem: Videos download but no .nfo files are generated.

Solution:

  • Check that Video .nfo files is enabled in Settings -> Core -> Media server files
  • Verify post-processing completed (check container logs)
  • Ensure write permissions in video directories
  • Look for errors in logs during post-processing phase

Getting Help​

If these solutions don't resolve your issue:

  1. Check the GitHub Issues page
  2. Provide details about your operating system
  3. Provide relevant logs when reporting issues:
    docker compose logs --tail=100 youtarr
  4. Include your configuration (without sensitive data)
  5. Describe steps to reproduce the problem