Debugging

Debugging#

Run with --log-level debug to show all log messages, often too much information for normal operation but useful when investigating a specific problem.

ytdl-sub builds on yt-dlp, which is in itself a complex tool. It performs an intricate and fragile task, web scraping, which in turn is subject to the whims of external services outside its control. Finally, because ytdl-sub is a lower-level tool, many users, if not most, will have problems getting their configuration working and it can be difficult to determine when the root cause is their configuration, just a limit imposed by the services, or, least likely, a bug in one of the tools involved.

To expedite resolution and conserve the limited resources of both yourself and volunteers, do as much investigation yourself as you can:

  1. Start by assuming the issue is your configuration:

    Review the guides to confirm your understanding. Increase output using the --log-level CLI option and read the output carefully for hints and clues. Use those clues to search the docs. Read the reference docs of the involved ytdl-sub components.

  2. Try to determine if the issue is happening in yt-dlp or ytdl-sub:

    The user’s configuration tells ytdl-sub how to run yt-dlp. yt-dlp handles all the web scraping and downloading. ytdl-sub then assembles the files and metadata produced by yt-dlp and places them in your library.

    If the issue is happening while scraping or downloading from the external service, then it’s happening in the running of yt-dlp. Look for output showing failed downloads, 403 errors, or signs of throttles. That doesn’t mean it’s a bug in yt-dlp, it could be in how your configuration tells ytdl-sub to run yt-dlp or limits imposed by the service that are constantly changing, but you may be able to find answers from other yt-dlp users running into similar issues.

    See the yt-dlp known issues and search their issues for clues and hints. Read the comments for more understanding, workarounds, and maybe even fixes. If you still don’t understand the cause after reading everything you can find there, try to find help in the yt-dlp Discord.

  3. If the issue is happening in ytdl-sub, reach out for help:

    Once you’ve done everything you can to get your configuration working and you’ve determined that the issue isn’t happening in yt-dlp, look for answers in ytdl-sub:

    1. Cut your configuration and subscriptions down to the minimum that reproduces the issue.

    2. Run with the --log-level debug CLI option and copy the full output.

    3. Search the ytdl-sub issues using clues and hints from the output.

    4. Open a support post in Discord with those details and all other relevant details.

    5. If someone from the Discord discussion directs you to, then open a new issue with those same details.