social-auto-upload: What Breaks, and Why (2026)

Most write-ups about a self-hosted posting tool stop at "it installed successfully." With social-auto-upload that's the easy part, roughly ten minutes. The real work starts the following week, when a platform changes a page and your scheduled posts quietly stop going out.

This is a guide to that part. It's the fourth most-starred tool in this niche (13.7k stars, 2.3k forks) and it does something genuinely useful, so it's worth running well rather than running blind.

What it actually is

A Python backend plus a Vue frontend that drives a real browser (via Playwright/patchright) to post on your behalf. It does not use platform APIs. That single design choice explains everything else in this article, both the reach and the fragility.

Coverage, as the project's own table reports it:

Platform	Video	Image/text	Scheduled	CLI
Douyin	✅	✅	✅	✅ (most complete)
Bilibili	✅	❌	✅	✅
Xiaohongshu	✅	✅	✅	✅
Kuaishou	✅	✅	✅	✅ (early)
WeChat Channels	✅	❌	✅	❌
Baijiahao	✅	❌	✅	❌
TikTok	✅	❌	✅	❌
YouTube	✅	❌	❌	✅

The CLI shape is consistent once installed:

sau douyin login --account <account_name>
sau douyin upload-video --account <account_name> --file videos/demo.mp4 --title "..." --desc "..."
sau youtube upload-video --account <account_name> --file videos/demo.mp4 --title "..." --visibility public

Sessions are cookie-based, one file per account name.

Two risks the README doesn't put up front

There's an open security audit. Issue #214 reports missing authentication, path traversal, and CSRF vulnerabilities, and it's still open. Combine that with what the tool holds, which is live session cookies for every social account you connect, and the conclusion is not subtle: run this on your own machine or a private network, never on a public-facing server, and never alongside anything else that's exposed. A compromise here doesn't leak a database, it hands over your accounts.

There's no declared license. As of July 2026 the GitHub API reports no license for the repo, and issue #236 is an open question about precisely that. No license is not the same as permissive: default copyright applies, and permission has not been granted. Fine for personal use, genuinely risky if you're building a paid service on top of it. Ask the maintainer before you commit.

The failure modes, in the order you'll hit them

1. Login gets stuck at the QR code

The most common report, and usually not your fault. On 2026-07-21 WeChat Channels switched its login QR to a qrconnect iframe and the extraction logic stopped finding the code (#252). Douyin has produced the same class of report repeatedly.

What to do: check whether an issue already exists for your platform before you debug your own setup. If the QR never renders, the selector is looking in the wrong place and no amount of reinstalling fixes it. Pull the latest commit first, since the maintainer patches these quickly during active phases.

2. SMS second verification interrupts you

The project flags this itself: Douyin may demand SMS verification mid-login. The code is expected in verify_code.txt, or you type it manually. If your automation is unattended, this is a hard stop by design, and it should be. Anything that fully automates around a verification code is a ban risk.

3. Headless mode gets flagged as automation

Headless is the project's current priority, so browsers run in the background. Platforms have gotten good at detecting exactly that. If logins succeed with a visible window and fail headless, you've found this one rather than a bug.

The uncomfortable truth: this is an arms race you don't control. Some weeks headless works, some weeks it doesn't. Build your posting schedule with enough slack that a broken week isn't a crisis.

4. YouTube uploads die at 99%

The README says it plainly: wait for progress to reach 100% before clicking publish. Interrupting mid-upload leaves a partial. If you're in a region where YouTube is blocked, you also need a proxy set in conf.py:

YT_PROXY = "http://127.0.0.1:7890"

YouTube also has no scheduled posting here, unlike most of the other platforms. Worth knowing before you build a calendar around it.

5. Bilibili installs something at runtime

Bilibili support auto-installs biliup when first used. Surprising if you're in a locked-down environment or auditing what your machine pulls. Its QR code is written to qrcode.png when the terminal can't render it, which is also where to look if the login "does nothing."

6. Nothing works and you cloned the zip

A recurring report is a downloaded source zip producing errors on every path at once. Use git clone. Also note requirements.txt is described as mostly legacy compatibility, so follow docs/install.md rather than assuming the requirements file is the install path.

The thing to internalize

Every failure above traces back to the same root: this tool automates a UI that other companies change without telling you. API clients break when a version is deprecated, with notice. Browser automation breaks when a designer ships a redesign, with none.

That isn't an argument against it. Most of these platforms don't offer a posting API you can actually use, so browser automation is the only door. But it changes how you should plan: budget maintenance time, keep the repo updated, watch the issue tracker for your platforms, and never let a single unattended chain be the only thing standing between you and an empty content calendar.

Where this sits in a content pipeline

Worth being clear about scope: social-auto-upload is a distribution tool. It moves finished files to platforms. It doesn't make anything.

Which means if you're using it, you already have the harder problem: enough video to be worth automating the posting of. A seller running 3 to 5 posts a day needs 20 to 35 videos a week, and no upload automation helps with that.

That's the part Riffkit does. You give it one short video that already worked, a TikTok link or an upload, and it rebuilds that video's formula, meaning the hook, the pacing, and the emotional beats, as new footage with your product in it. It never re-uploads the source clip. Output is post-ready and generated natively in 9 languages, so the file that lands in your folder is the file you post.

The two fit together cleanly, and the honest division is: we generate, it distributes. If you want the generation side driven from a terminal the same way, Riffkit installs as an agent skill:

Read https://riffkit.ai/SKILL.md and follow the instructions to set up Riffkit.

Notably, social-auto-upload ships docs/agent-bootstrap.md for the same reason, so if you're already running agents, both halves of the pipeline can be scripted. If you're assembling a wider agent stack around this, Corey Haines' marketingskills repo covers the ad-creative and copy side.

And go star the repo. Maintaining browser automation against eight platforms that all keep moving is thankless work, and it's holding up a lot of people's posting schedules. For where posting volume actually comes from, see how many videos a TikTok Shop affiliate should post.