> For the complete documentation index, see [llms.txt](https://docs.tumbler.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tumbler.app/getting-started/common-issues.md). # Common issues ## Who this is for Support engineers and on-call engineers who investigate subscription and fetcher failures. ## What you can do * Quickly validate a subscription without backend logs (self-serve curl checks). * Find common errors and fixes. * Prepare data for incident investigation. ## Quick validation checklist (self-serve) * **HTTPS 443:** final URL responds over `https://...:443`, with no redirects to `http`, non-standard ports, or third-party domains. * **Allowed redirects only:** no file-sharing/drives/`file:`/`http:` destinations; no more than 3 in a row. * **Size < 2 MB:** body after possible decoding/base64 does not exceed 2 MB. * **Valid VLESS links:** each line is `vless://@host:port` (no `vmess://`, no spaces); node name after `#` is optional. * **Base64 body (if used):** string fully decodes without errors (`base64 -d`), with no spaces/logs before or after. * **Metadata uses supported keys:** use fields from [subscription/metadata.md](/subscription-contract/metadata.md); no typos or extra headers/meta lines. * **ETag/304 work:** first request returns a strong `ETag`, second request with `If-None-Match` returns `304`. * **Mirrors:** `meta.mirrors` contains only absolute `https://` URLs that are reachable and return the same `ETag`/body. ## Common problems * **"Nothing imports"** - response is not UTF-8/has BOM, junk at the beginning (HTML, logs), lines are not `vless://`, base64 is invalid or truncated. Check `Content-Type`, encoding, remove empty/broken lines, validate UUIDs/ports. * **"Updates do not arrive"** - missing `ETag`, or `If-None-Match` always gets `200`; link order changes every time, making `ETag` jump. Use stable sorting and return a strong `ETag`, otherwise 304 will not happen. * **"Device limit does not work"** - installation slot lives 24 hours since activity (sync/heartbeat/connect). If the device is silent for >24 hours, the slot is released; deleting the subscription releases it immediately. Make sure `installation-limit` is set and users understand the 24-hour window. * **`connection-limit` does not allow >=2** - values >1 work only with **\[PAID]** Advanced Connection Control (ACC) (`meta.capabilities=["advanced_connection_control"]`; see [features/overview.md](/features/overview.md)). Without it, the server treats the value as `1`. * **"Mirrors are not used"** - `meta.mirrors` has non-absolute URLs, HTTP instead of HTTPS, or an unreachable/different mirror. Mirrors are applied only after the primary URL fails; they must return the same content and `ETag`. * **"Limits do not work / always 429"** - `Cache-Control: max-age` is too small or the body changes too often. Set a reasonable `max-age`/`ETag` and make sure clients are not retrying without backoff. ## curl diagnostics (self-serve) * Check availability, redirects, and headers: ```bash curl -I -L --max-redirs 3 --connect-timeout 5 https://example.com/sub ``` Verify `200/304`, `Content-Type`, `Cache-Control`, `ETag`, no redirects to `http`, and no unexpected headers. * Check body size: ```bash curl -sSL -w 'download=%{size_download} bytes\n' -o /dev/null https://example.com/sub ``` If `size_download` >= 2\_000\_000, reduce node count or remove extra fields. * Check `ETag`/`304`: ```bash # Extract first ETag, remove ETag:/W/ prefix, quotes, and \r etag=$(curl -sD - -o /dev/null https://example.com/sub \ | awk 'BEGIN{IGNORECASE=1} /^etag:/ {gsub(/^etag:[[:space:]]*/, ""); gsub(/^W\//, ""); gsub(/"/, ""); gsub(/\r/, ""); print; exit}') curl -s -o /dev/null -D - -H "If-None-Match: ${etag}" https://example.com/sub ``` The command extracts the first `ETag`, removes the `ETag:` prefix, weak prefix `W/`, quotes, and `\r`. Expected result is `304 Not Modified`. If the response is `200` again, the server is not using `If-None-Match`. * Check base64 body (if the subscription returns base64): ```bash curl -sSL https://example.com/sub | base64 -d >/tmp/subscription.raw && wc -c /tmp/subscription.raw ``` `invalid input` means extra characters/spaces/junk in the response. * Find broken VLESS links: ```bash # Basic UUID/host/port check (port is any digits; range 1-65535 is not checked; UUID version is not checked) curl -sSL https://example.com/sub \ | grep -nEv '^$|^#|^vless://[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}@[^\s:]+:[0-9]+(#.*)?$' ``` The pattern checks UUID in `8-4-4-4-12` format, host without spaces/colons, numeric port, and optional `#comment` at the end. Empty output means all lines are valid. Non-empty output means invalid lines exist; inspect the line numbers printed by `grep`. The pattern is basic (it does not check port range 1-65535 or UUID v4 version) and is meant to catch junk; use additional validation for strict checks. * Check mirrors: ```bash curl -sSL https://example.com/sub | grep -iE '^(#\s*)?(mirrors|x-subscription-mirrors)' # Then request each mirror explicitly: curl -I https://mirror1.example.com/sub ``` All mirrors must be available over HTTPS and return the same `ETag`/body. The value is read from `meta.mirrors`; it may come from meta lines (`# mirrors:`) or equivalent `X-Subscription-Mirrors` header. ## Provider FAQ (what to tell users) * **Does not import / "empty config"** - check that the subscription is UTF-8, without HTML/logs, and contains at least one valid `vless://...` or supported JSON/Xray/sing-box outbound. Give the user the current add link and last check time. * **"No updates"** - updates arrive when the subscription body/`ETag` changes. If content did not change or line order is random, the client either sees the old version or downloads the same body again. Explain `Cache-Control` and stable sorting expectations. * **"Device/connection limit triggered"** - slot is released after 24h without activity or immediately after subscription deletion. More than one concurrent connection requires ACC plan (`advanced_connection_control`). * **"Mirror does not help"** - mirrors are fallback. Make sure full HTTPS URLs are listed and return the same content; if the primary location returns 200, the client will not switch. * **"Why no 304?"** - server does not support `If-None-Match` or `ETag` changes too often (floating link order). Fix order and return a strong `ETag`. ## See also * [operations/caching-and-304.md](/after-first-launch/caching-and-304.md) * [operations/mirrors-and-migration.md](/after-first-launch/mirrors-and-migration.md) * [features/overview.md](/features/overview.md) * [subscription/metadata.md](/subscription-contract/metadata.md) * [subscription/examples.md](/subscription-contract/examples.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.tumbler.app/getting-started/common-issues.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.