KB-001 — "Getting API is not available" on the main page

KB-001 — “Getting API is not available” on the main page

Series: Bloqr Compiler Operations & Troubleshooting KB
Component: worker/worker.ts — Cloudflare Worker API entrypoint
Service URL: https://bloqr-backend.jk-com.workers.dev
Date Created: 2026-03-17
Status: Active

Symptom

The Angular SPA home page shows “Getting API is not available” on initial load at https://bloqr-backend.jk-com.workers.dev.

API fetches from the frontend to /api/version, /api/clerk-config, /api/turnstile-config, or /api/sentry-config may be returning non-200 responses, causing the Angular app to render the error state.

How the Home Page Gets API Availability

The Angular frontend bootstraps by calling a set of config/version endpoints. If any fail with an error status, a guard in the home component sets the “API not available” display state. The worker serves these at the following paths (all GET, public, no auth required):

Endpoint	Purpose
`GET /api/version`	Returns compiler version and latest deployment record from D1
`GET /api/clerk-config`	Returns Clerk publishable key (or `null`)
`GET /api/turnstile-config`	Returns Turnstile site key and enabled flag
`GET /api/sentry-config`	Returns Sentry DSN for frontend RUM

All of these run before the ZTA auth chain (they are pre-auth handlers in _handleRequest). If they’re failing, the cause is at the infrastructure layer, not the auth layer.

Diagnostic Commands

Run these from any terminal. A healthy deployment returns 200 with a JSON body on all four.

# 1. Test root API info (bypasses HTML redirect)
curl -s "https://bloqr-backend.jk-com.workers.dev/api?format=json" | jq .

# 2. Test the version endpoint (hits D1)
curl -s "https://bloqr-backend.jk-com.workers.dev/api/version" | jq .

# 3. Test health (checks D1, KV, compiler binding, auth, gateway)
curl -s "https://bloqr-backend.jk-com.workers.dev/health" | jq .

# 4. Test metrics (hits KV METRICS namespace)
curl -s "https://bloqr-backend.jk-com.workers.dev/metrics" | jq .

# 5. Tail the live worker log
wrangler tail

Root Cause Decision Tree

❶ Does `GET /health` return `"status": "healthy"`?

If NO — check the services object in the health response for the failing subsystem:

{
  "status": "down",
  "services": {
    "database": { "status": "down" },
    "cache":    { "status": "healthy" },
    "auth":     { "status": "degraded", "provider": "none" },
    "compiler": { "status": "degraded" },
    "gateway":  { "status": "healthy" }
  }
}

Failing service	Likely cause	Fix
`database: down`	D1 binding broken or migration pending	Re-deploy; run pending migrations
`auth: degraded, provider: none`	Neither `CLERK_JWKS_URL` nor `JWT_SECRET` is set	`wrangler secret put JWT_SECRET`
`compiler: degraded`	`BLOQR_COMPILER_DO` Durable Object binding missing	Deploy tail worker first; re-deploy
`cache: down`	`COMPILATION_CACHE` KV namespace missing/unbound	Check KV namespace in Cloudflare dashboard

❷ Does `GET /api/version` return `503`?

This endpoint calls getLatestDeployment(env.DB). A 503 means env.DB is null — the DB D1 binding is missing from the deployed worker.

Check: wrangler d1 list — confirm bloqr-backend-app-db exists and the ID matches wrangler.toml.

wrangler d1 list
# Should show: bloqr-backend-app-db  3e8e7dfe-3213-452a-a671-6c18e6e74ce5

❸ Is CORS blocking the browser request?

The worker reads the CORS_ALLOWED_ORIGINS value at runtime. There are two sources for this value and they can conflict:

Source	Value	Precedence
`wrangler.toml [vars]`	`"http://localhost:4200,...,https://bloqr-backend.jk-com.workers.dev"`	Lower
`wrangler secret put CORS_ALLOWED_ORIGINS`	Whatever was set when the command was last run	Higher — overrides [vars]

If a secret was previously set with an outdated or incorrect value, it silently overrides the [vars] entry.

# Check which secrets exist
wrangler secret list

# If CORS_ALLOWED_ORIGINS is listed as a secret, re-set it:
wrangler secret put CORS_ALLOWED_ORIGINS
# Enter: http://localhost:4200,http://localhost:8787,https://bloqr-backend.jk-com.workers.dev

To verify, open Chrome DevTools → Network tab, look for the OPTIONS preflight or the failing GET, and check the Access-Control-Allow-Origin response header.

❹ Is the `bloqr-tail` worker missing?

wrangler.toml declares:

[[tail_consumers]]
service = "bloqr-tail"

If bloqr-tail doesn’t exist in your Cloudflare account, wrangler deploy will fail silently or deploy a broken worker. This is the most common cause of a “everything looks fine in code” deployment that still doesn’t work.

# Deploy the tail worker first (from wrangler.tail.toml)
wrangler deploy --config wrangler.tail.toml

# Then re-deploy the main worker
wrangler deploy

❺ Does the Angular build exist in the ASSETS binding?

The [assets] binding points to ./frontend/dist/bloqr-backend/browser. If the Angular build artifact is missing (e.g., the frontend CI step failed or was skipped), the worker deploys without static assets. The SPA shell won’t serve, and the Angular app will never initialize.

# Trigger a fresh build manually
sh scripts/build-worker.sh

# Or re-run the full deploy (which runs the build script)
wrangler deploy

Worker Code Reference

The relevant request routing lives in _handleRequest in worker/worker.ts:

GET /api — handleInfo() — browser requests (Accept: text/html) redirect to /api-docs; API clients must send Accept: application/json or append ?format=json
GET /api/version — queries D1 via getLatestDeployment(env.DB); returns 503 if env.DB is null
GET /api/clerk-config — returns CLERK_PUBLISHABLE_KEY (or null); no auth, cached 1 hour
GET /api/turnstile-config — returns TURNSTILE_SITE_KEY and enabled flag; no auth, cached 1 hour
GET /api/sentry-config — returns Sentry DSN for frontend RUM; no auth
GET /health — performs live probes of all bound services; returns granular per-service status

handleInfo() content negotiation detail:

const wantsHtml = Boolean(env.ASSETS) && accept.includes('text/html') && searchParams.get('format') !== 'json';
if (wantsHtml) {
    return Response.redirect(new URL(API_DOCS_REDIRECT, request.url).toString(), 302);
}

Frontend API fetches must send Accept: application/json or omit the Accept header to avoid being redirected to /api-docs.

ZTA Security Note

All four config endpoints are intentionally pre-auth — they expose no secrets, only public keys and feature flags. The Turnstile site key, Clerk publishable key, and Sentry DSN are all public values by design. If these endpoints are returning auth errors (401, 403), something has changed in the auth chain that should not have touched these paths. File a separate bug.

Resolution Summary

Symptom	Root Cause	Fix
`"API not available"` on home page	D1 DB binding missing	`wrangler deploy` after confirming D1 namespace exists
`"API not available"` on home page	`CORS_ALLOWED_ORIGINS` secret overrides `[vars]` with stale value	`wrangler secret put CORS_ALLOWED_ORIGINS`
`"API not available"` on home page	`bloqr-tail` service not deployed	Deploy tail worker, then re-deploy main worker
`"API not available"` on home page	Angular build missing from ASSETS	Run `sh scripts/build-worker.sh` and re-deploy
`GET /api/version` returns 503	`DB` D1 binding null	Verify D1 database ID in `wrangler.toml` matches dashboard
`GET /health` shows `auth: degraded`	`CLERK_JWKS_URL` and `JWT_SECRET` both unset	Set `JWT_SECRET` secret or configure Clerk

KB-002 — Hyperdrive binding connected but database service reports down
KB-003 — Database Down After Deploy — Live Debugging Session (2026-03-25)
KB-004 — Prisma WASM instantiation error on Cloudflare Workers
KB-005 — Better Auth Cloudflare integration issues: Worker CPU timeout and silent rate limiting bypass

Feedback & Contribution

If you discovered a new failure mode while using this article, please open an issue tagged troubleshooting and documentation in jaypatrick/bloqr-backend with the details so it can be captured in a follow-up KB entry.