Frequently Asked Questions (FAQ)

If your issue isn't listed here, feel free to submit an Issue or Discussion on GitHub.

Cloudflare Quick Deploy Error: `An unknown error occurred`

This may be a GitHub/GitLab authorization issue:

Solution Steps:

Q: How do I keep my Fork in sync with upstream?

Open your forked repository homepage and click the Sync fork button in the top right.
Or locally execute git remote add upstream https://github.com/7Sageer/sublink-worker.git, then sync with git fetch upstream && git merge upstream/main.

Q: Why can't I access the generated subscription in my region?

*.workers.dev domains are often blocked in certain regions.
We recommend binding a custom domain in Cloudflare Pages/Workers and hosting DNS resolution on Cloudflare for flexible Rules/SSL configuration.
If you can't bind a domain temporarily, use a proxy to access or deploy the subscription fetch logic on an overseas server.

Q: How do I ensure KV persistence when deploying with Node/Docker?

We recommend using the repository's built-in docker-compose.yml: it will start Redis 7 alongside the worker and load redis.conf to enable RDB snapshots, with data written to the redis-data volume.
Compose uses the GitHub Actions-pushed image ghcr.io/7sageer/sublink-worker by default. You can change to a self-built image via SUBLINK_WORKER_IMAGE.
If you prefer hosted KV, configure KV_REST_API_URL & KV_REST_API_TOKEN to directly connect to Upstash/Vercel KV. When both are unset, it falls back to in-memory storage. You can disable this with DISABLE_MEMORY_KV=true.

Before saving base configs or short links, ensure the Worker is connected to persistent KV.
If you replace default rule sets or add new languages, please update the documentation in your PR.
When reporting issues, please include: deployment method, runtime logs, input samples, and Worker version for easier troubleshooting.