Troubleshooting

Start by separating Web/BFF, API gateway, scraper module, and DLP failures. They have different health and authentication boundaries.

Web stays on verification

Check the browser network panel for /api/instance, /api/session, and /api/verify.

• NEXT_PUBLIC_TURNSTILE_SITE_KEY must be the site key registered for the deployed Web hostname.
• Pinchana API must have the matching private TURNSTILE_SECRET_KEY.
• TURNSTILE_EXPECTED_HOSTNAME must match the Web hostname.
• Keep TURNSTILE_EXPECTED_ACTION=turnstile-spin-v1 unless both projects are deliberately changed together.
• TURNSTILE_SESSION_SECRET must be a random value of at least 32 characters.

Cloudflare test keys are useful for local development. Production must use the real site/secret pair.

The URL is rejected or unsupported

Normal API routing only covers the URL families listed under Supported platforms. Use a complete http:// or https:// URL.

Ordinary YouTube URLs require DLP in the Web client. youtube.com/watch must not be treated as a YouTube Shorts URL just because the API contains a shorts module.

Machine clients should use POST /v1/scrape; /scrape is compatibility-only.

Scrape succeeds but media does not load

Machine media routes require the same X-API-Key authentication as the scrape request. Web media routes require a valid signed browser session.

For Web, inspect /api/media/..., not the upstream API URL. The Next.js media proxy forwards range requests and the HttpOnly session that browser media elements cannot attach themselves to the API origin.

A missing file can also mean the shared cache was cleaned or a deployment does not share the same scraper-cache volume between the gateway and module that created the asset.

YouTube options are disabled

Web enables DLP controls only after /api/capabilities reports a DLP capability with available: true and protocol: 2.

On the API host:

docker compose --env-file .env --profile dlp ps
python scripts/dlp-prod-preflight.py --env-file .env --phase enable

Keep DLP_ENABLED=false until Redis, VPN, DLP API, orchestrator, worker image, storage, networking, and the canary are ready. Enabling only the flag does not make a broken DLP deployment healthy.

A custom API instance cannot connect

The official Web client requires:

• an HTTPS API origin in production;
• GET /web/identity to return a project-issued certificate envelope;
• the certificate origin claim to match the entered origin exactly;
• an unexpired Ed25519 signature verifiable by the Web deployment’s PINCHANA_INSTANCE_PUBLIC_KEY;
• the certificate’s public Turnstile site key to match the instance’s browser flow.

A 503 from /web/identity usually means the certificate was not configured inside the API server container.

API health or VPN problems

Check the public gateway first:

curl --fail-with-body --silent --show-error http://127.0.0.1:8080/health

In production, scraper traffic uses Gluetun’s network namespace. Do not use docker restart gluetun; recreate it so credentials and environment are applied correctly:

docker compose --env-file .env up --detach --force-recreate gluetun

Then inspect gateway/module logs and GET /admin/vpn/status with an authorized machine key when deeper VPN diagnostics are necessary.

YouTube Shorts asks for authentication

The shorts service can read Netscape-format cookie files from the host directory configured by SHORTS_COOKIES_DIR, mounted read-only at /run/pinchana-cookies.

For the current container, running as root, a conservative host setup is:

sudo chown -R root:root secrets/yt-cookies
sudo chmod 700 secrets/yt-cookies
sudo chmod 600 secrets/yt-cookies/cookies.txt

With rootless Docker, use the host user that runs Docker instead. Never commit cookies to Git.

Useful diagnostics

Pinchana Web’s About section can copy a sanitized diagnostic summary containing public build revisions, coarse browser/device state, current activity, service count, and DLP availability. It intentionally omits submitted URLs, media metadata, custom origins, secrets, IP addresses, and the full user agent.

For API deployment issues, prefer docker compose ... config --quiet, docker compose ps, targeted logs, /health, and the provided preflight/update scripts over dumping full rendered configuration.