IRIDESC E UX · COMMAND
v31 · Program Primary Revision
00 · START HERE01 · Architecture & Folder Map02 · First-Time Cloudflare Setup — Every Click03 · Admin & Employee Logins04 · D1, R2, Variables & Secrets05 · Iridesceux Site Operations06 · HVN Site Operations07 · Command Daily Operations08 · Master Control & Broadcast09 · Ads, Commercials & Station IDs10 · Analytics, Safety & Reporting11 · OBS, Server & Broadcast Agent12 · Security, Backups & Offboarding13 · Troubleshooting — Symptom by Symptom14 · Go-Live Checklist15 · Quick Reference16 · Production Readiness Tests17 · HVN Viewer Accounts18 · Release Audit Results19 · Cloudflare Team-Domain Recovery20 · Deployment & Change Matrix21 · External Services & API Tokens22 · Rundown, Traffic & Local EPG23 · Dolby Vision & HDR
INTERNALSTEP-BY-STEP

Troubleshooting — Symptom by Symptom

Do not guess. Match the exact symptom to the exact layer and follow only that recovery path.

Rule: identify the failing layer first

Use the symptom to choose one layer. Do not “fix everything” at once.

SymptomLayer
522 / wrong originPages custom domain / DNS
Unable to find Access organizationZero Trust team domain / Access org
OTP deniedAccess policy / identity provider
Access succeeds, /api/command/me says Authentication requiredCommand JWT env/AUD/team domain/deployment
503 COMMAND_DBD1 binding
Upload 503/failsR2 binding / auth / upload size
Button works in demo onlyBackend/API deployment
OBS action never happensAgent/service token/OBS

522 Connection timed out on command.iridesceux.com

  1. Open the raw Command *.pages.dev URL. If that is broken, fix Pages first.
  2. Workers & Pages → Command → Custom domains: verify command.iridesceux.com is attached and Active.
  3. DNS → search for command. Remove stale A/AAAA/manual CNAME records that point somewhere else.
  4. If you manually created a Pages CNAME without associating the domain in Pages, delete/fix it and use Pages → Custom domains → Set up a domain.
  5. If Access is already on the hostname and Pages refuses to attach the domain, temporarily remove the Access application, attach/activate Pages domain, then recreate Access immediately.
Official reference: https://developers.cloudflare.com/pages/configuration/custom-domains/
Official reference: https://developers.cloudflare.com/pages/platform/known-issues/
Official reference: https://developers.cloudflare.com/pages/configuration/custom-domains/

“Unable to find your Access organization”

Do not troubleshoot OTP first. Directly open:

https://iridesceux.cloudflareaccess.com

If the team-domain URL itself returns that error, the Access organization/team domain is the problem. Use document 19.

If the team-domain URL works but Command’s /cdn-cgi/access/authorized callback still shows the error, compare account/zone Access organization/application scope using document 19 and recreate the Command Access application only after the team organization is healthy.

Access login works, then /api/command/me says Authentication required

  1. Confirm you are testing the newest Command deployment.
  2. Confirm COMMAND_REQUIRE_ACCESS_JWT=true.
  3. Confirm CF_ACCESS_TEAM_DOMAIN=https://iridesceux.cloudflareaccess.com.
  4. Open Access app → copy the current Application Audience (AUD) Tag.
  5. Set CF_ACCESS_AUD to that exact value.
  6. If the Access application was deleted/recreated, assume the AUD changed and update Command.
  7. Confirm BOOTSTRAP_ADMIN_EMAIL exactly matches the authenticated email.
  8. Redeploy Command.
  9. Open a fresh Incognito session and authenticate again.
Do not “fix” this by enabling COMMAND_ALLOW_HEADER_AUTH in production. The code intentionally requires signed Access JWT verification.

/api/command/me is 404 or HTML

  1. Command Pages root must be command-app.
  2. Output must be public.
  3. functions/ must exist directly under command-app, beside public/.
  4. Deploy with Git integration or Wrangler; Cloudflare does not support Pages Functions through ordinary dashboard Direct Upload.
  5. Redeploy and retest.
Official reference: https://developers.cloudflare.com/pages/functions/get-started/

503 COMMAND_DB binding is not configured

  1. Cloudflare → D1: verify database exists.
  2. Wrangler: verify schema tables exist.
  3. Command Pages → Settings → Bindings: D1 variable name must be exactly COMMAND_DB.
  4. Confirm binding is applied to production environment as intended.
  5. Redeploy.
  6. Retest the newest deployment.

R2 upload fails

  1. Confirm authenticated Command identity first.
  2. Command Pages → Bindings: R2 variable name exactly COMMAND_ASSETS.
  3. Verify bucket exists and is selected.
  4. Redeploy after binding.
  5. Use a small test file. Generic Command asset upload route currently rejects files over 25 MB.
  6. Check browser Network response for the specific API error.

Demo mode appears on deployed site

  1. Make sure URL is HTTPS Pages/custom domain, not file://.
  2. Remove ?demo=1.
  3. Hard-refresh.
  4. Use Setup Doctor to prove backend Functions are reachable.

Access app creation error mentions clientless isolation/private destination

Return to the Access application’s Additional settings and disable the clientless/private-destination Browser Isolation option. Command uses a public hostname; do not enable a setting that Cloudflare restricts to private destinations.

Program Monitor blank

  1. Verify selected market.
  2. Open the HVN live-page URL directly.
  3. Check player source/feed URL.
  4. Check framing/security headers if the monitor embeds the page.
  5. Check whether private staging Access blocks the embedded request.
  6. Do not TAKE blind; restore monitor visibility first.

OBS command does nothing

  1. System Health: is Broadcast Agent online?
  2. Agent terminal: any authentication/network error?
  3. Verify BROADCAST_AGENT_TOKEN matches on both sides.
  4. If Access protects agent API, verify service-token ID/secret.
  5. Verify OBS WebSocket server enabled and password/URL correct.
  6. Verify exact scene/input names.
  7. Run harmless test scene switch.

Rundown / EPG / scheduled-break troubleshooting

SymptomCheck
Schedule exists in Command but not on HVNConfirm the correct market/day and press PUBLISH TO HVN WEBSITE. Draft days intentionally stay private.
Schedule shows on HVN but does not airConfirm APPROVE DAY FOR AIR, then confirm that market is armed for schedule automation. Publication is not air authorization.
Local viewer sees National EPG unexpectedlyConfirm the local day is published and inspect Inherit National. A published local day with inheritance enabled overlays local blocks on National; with no local day, National is the fallback.
Commercial plays but show skips aheadThat is a release blocker for file playout. v24 must expose timeline pause/hold and the public player must use it. Do not air until the scheduled-break hold test passes.
Wrong local commercial airsVerify break clock market ownership, selected rundown market, day air approval, and local-vs-National overlap.
National Screen Bug makes program blackConfirm the graphic is on the independent graphics bus. For AE black-matte exports use Screen-key mode; true-alpha assets use Normal mode.
Canonical internal documentation · v31 · Program Primary Revision. The application baseline includes native program playout, full-day National/local rundown and traffic, plus verified Dolby Vision HLS delivery with canonical uploaded masters. Rehearse all on-air changes on staging before production.

Automatic Premium HLS is UNAVAILABLE / FAILED

  1. Setup Doctor: check Premium media auto-packager.
  2. Confirm MEDIA_PACKAGER_URL and MEDIA_PACKAGER_TOKEN exist on Command.
  3. Open the media-packager Worker /health endpoint.
  4. Confirm its D1 ID and R2 bucket point to the same Command resources.
  5. If an older error says Dolby Vision signaling could not be derived or preserved, first deploy the current Dolby-aware media-packager and retry the same uploaded master. A separate mezzanine or manual HLS package is not required when the uploaded MP4/MOV already contains valid Dolby Vision signaling.