# Cache options and troubleshooting Cache options are a trailing sequence on the **proxy password**. Username options such as pool, country, city, and session stay unchanged. The suffix is the complete opt-in: Litport does not silently enable caching for a token, and a request without it remains an ordinary proxy request. ```text PASSWORD_cache-[_cacheduration-][_cacheignoreheader-1] ``` Examples: ```text username:password_cache-images,fonts username_country-us_sid-crawl-42:password_cache-all_cacheduration-30 username:password_cache-scripts_cacheduration-60_cacheignoreheader-1 ``` Litport first tries the complete password literally. This preserves an existing password that happens to end with cache-like text. Only when that exact credential does not exist does Litport parse a valid trailing cache sequence and authenticate the base password. ## Options | Option | Values | Behavior | | --- | --- | --- | | `_cache-` | `images`, `scripts`, `fonts`, `all`, a supported extension, or a comma-separated mix | Enables eligible types. Values are case-insensitive; generated values are lowercase. | | `_cacheduration-` | Integer minutes, minimum 1 | Defaults to 120 when absent or below 1. Operational eviction may remove an entry sooner. | | `_cacheignoreheader-1` | Literal `1` | Ignores origin freshness/privacy directives for otherwise eligible responses. Its requested TTL starts when Litport receives and stores the complete response; origin `Date` and `Age` do not subtract from it. Absolute safety exclusions still apply. | Extensions are `png,jpg,jpeg,gif,svg,ico,webp`, `js,css,wasm,map`, and `woff,woff2,ttf,eot,otf`. An empty list or unsupported value leaves the request uncached without breaking proxy authentication. ## Request outcome ```docs-figure cache-outcomes Every cache-mode request resolves to a hit, miss, or bypass. Only bytes actually delivered from a cached body are free. ``` - **Hit:** response-body bytes delivered from the hub entry are free. A client abort or cache read error remains visible as delivery status and is never moved into billable traffic. - **Miss:** Litport opens the normal upstream path. Request and response bytes are billed normally. A valid complete response may be stored for another request. - **Bypass:** Litport sends the request upstream without using or storing a cache entry. Traffic is billed normally. There is no proprietary or authoritative Litport cache-hit response header. `Age` can appear or increase on a cached response, but origins and CDNs can set it too; use Traffic statistics or the [Account API](/docs/api/usage) for hits, misses, bypasses, free bytes, and pay-per-GB savings. Manual purge is not available. ## Eligibility and absolute exclusions Litport stores only HTTPS `GET` responses with status 200 and a path ending in a selected extension. The exact URL, including query order and encoding, identifies the object. In standard mode, `s-maxage` overrides `max-age`; the shorter valid origin freshness and requested duration wins. The requested duration is a hard maximum: when a standard-mode origin response already has a corrected `Age` at or above it, Litport does not store that response. With `_cacheignoreheader-1`, the requested TTL starts when Litport receives and stores the complete response, without subtracting origin `Date` or `Age`. These requests always bypass, even with `_cacheignoreheader-1`: - `Authorization`, `Cookie`, `Range`, or conditional request headers - request `Cache-Control: no-cache`, `no-store`, or `max-age=0`, or `Pragma: no-cache` - `Set-Cookie`, unsupported `Vary`, partial content, oversized responses, or incomplete bodies - service workers, extensionless URLs, APIs, documents, video, audio, and archives - plain `http://` targets, SOCKS5 ingress, UDP, and HTTP/3/QUIC `_cacheignoreheader-1` may override missing or blocking response cache directives, but not the list above. Because a stored entry is shared on one hub, use this option only for public unauthenticated assets that are identical for every requester. ## Protocol behavior HTTP/1.1 and HTTP/2 clients are supported for cache-mode HTTPS requests. Litport can also negotiate HTTP/2 on the verified origin leg. HTTP/3 uses QUIC over UDP, while the explicit Litport HTTP proxy path is TCP CONNECT; the QUIC request therefore does not enter this cache path. Applications often fall back to HTTP/2, but Litport does not claim HTTP/3 caching. The Litport proxy endpoint may be written as `http://HUB:PORT`. Eligibility is based on the target URL, which must be `https://...`. ## Troubleshooting | Symptom | Likely reason | What to do | | --- | --- | --- | | TLS issuer or unknown-CA error | The client process does not trust the Litport root | Configure the CA in that process; verify the downloaded fingerprint. | | Works without `_cache-`, fails with it | Separate app trust store or certificate pinning | Configure the app you own, or omit cache mode. Third-party pinning cannot be bypassed. | | First request is billed | The selected hub is cold | Repeat the identical eligible URL through the same hub. | | Requests became cold after changing hub | Cache storage is local, not replicated | Warm the new hub or keep one hub for that workload. | | Every request is a miss | URL/query differs, entry expired/evicted, or response cannot be stored | Compare exact URLs and inspect origin cache headers and status. | | A fresh-looking origin response is not stored in standard mode | Its corrected `Age` is already at or above the requested duration | Request a longer duration when appropriate, use a response with remaining freshness, or use the advanced override only for public unauthenticated assets. | | A cached response is stale or must change immediately | Manual purge is not available | Use a shorter TTL or versioned URLs, then wait for the entry to expire. | | Request is a bypass | Method, headers, response, target scheme, ingress, or extension is excluded | Use an eligible public HTTPS GET or continue with normal billed proxying. | | Plain HTTP is never cached | Its origin leg has no authenticated integrity | Keep using it normally; a CA cannot make plain HTTP eligible. | For transport-sensitive targets, read [TLS and HTTP fingerprints](/docs/proxy-cache/transport-fingerprints).