Troubleshooting

Solutions for common Platform-layer issues. Product-specific problems (Cartographer crawl, Clone fidelity) are covered in those product docs.

Authentication

401 Unauthorized on API calls

403 Forbidden

Authenticated but not a member of the target org, or role insufficient. Ask an admin to invite you or upgrade your role.

SSO login fails

• Check WorkOS status
• Orgs with sso_enforced=true block magic-link fallback — wait for SSO recovery
• Orgs with sso_enforced=false may use verified-email magic link temporarily

MCP OAuth loop

1. Clear MCP client cached tokens
2. Re-add server https://mcp.molar.cloud/mcp
3. Ensure browser completes consent with required scopes
4. Verify PKCE — clients must use S256

CLI auth

molar login not working

molar login accepts a PAT via --token, MOLAR_TOKEN, or an interactive prompt. Supported today:

molar login --api-url https://api.molar.it --token molar_pat_xxxx
# verify:
curl -s -H "Authorization: Bearer $MOLAR_TOKEN" https://api.molar.it/api/v1/me

Or add to ~/.config/molar/config.toml:

api_url = "https://api.molar.it"
token = "molar_pat_xxxx"

MOLAR_E020 — surface not installed

MOLAR_E020: "guard" is not installed

Install the missing runner or use cloud runs from the dashboard. See docs.molar.it/errors/E020.

Run molar doctor for dependency status.

Scenario compiler

Validation errors (MOLAR_S0xx)

molar scenarios validate --json

• Unknown frontmatter key — typo; schema is strict
• Unknown verb — check .molar.md verb list
• Unresolved variable — ${secrets.X} not in keychain / Molar API

Compile succeeds but run fails

• Re-run molar scenarios compile after edits (cache is content-hash keyed)
• Check ${env.BASE_URL} is set for target environment
• Ensure Clones are started if scenario declares clones:

Runs & Guard

molar run exits immediately

1. molar doctor — Playwright browsers, guard runner binary
2. molar scenarios compile — ensure .compiled/ exists
3. Install browsers: npx playwright install

GitHub check not appearing

• Confirm Molar GitHub App installed on repo
• Required check name matches org settings
• Scenario must be approved and linked to repo path filters

Run stuck in Queued

• Check Molar API / Guard worker health
• Dashboard Settings → Services or GET /api/v1/services/health
• Redis connectivity for live progress

MCP

Capability manifest for expected tools: molar-capabilities.json.

Quotas & billing

429 Quota Exceeded

{
  "error": "Quota Exceeded",
  "resource": "runs_per_day",
  "limit": 200,
  "used": 200
}

Daily quotas reset 00:00 UTC. Contact support@molar.it to raise caps.

402 LLM spend cap exceeded

Switch affected capabilities to BYOK or raise debugger budget on Billing.

Billing page empty / Lago errors

Self-hosters: ensure Lago profile is up (docker compose --profile billing) and LAGO_API_KEY seeded.

Molar API & dashboard

503 unavailable

Readiness probe failed — Postgres, Redis, or upstream API down.

• Combined mode: verify PLUMBING_CONTROL_PLANE_URL reachable from dashboard
• Standalone mode: non-local proxy paths intentionally return 503

Dashboard proxy errors

Check env upstreams:

SSE logs not streaming

Requires ioredis + Redis. Without Redis, log stream returns 501 — use static log fetch instead.

Agent comms

Webhook signature failures

• Set MOLAR_AGENT_COMMS_SIGNING_KEY to match your agent comms dashboard
• For local dev only: MOLAR_AGENT_COMMS_REQUIRE_SIGNATURE=false

OTP poll always empty

• Confirm SMS/email reached the synthetic mailbox (check agent comms logs)
• Verify totp_identifier matches sender
• Check MOLAR_OTP_POLL_SECRET on poll requests
• Inspect python/payloads/ locally

LLM gateway

Workers cannot reach gateway

curl -H "Authorization: Bearer $MOLAR_LLM_SERVICE_KEY" \
  $MOLAR_LLM_BASE_URL/health

Verify MOLAR_LLM_BASE_URL and service key match gateway config.

Wrong model / capability

Check org model_routing in settings; integration ID must exist (molar-managed or BYOK).

Getting help

Include org id, run id, and timestamp when reporting failed runs.

Related

• Install & initialize
• Environment variables
• OAuth & authentication
• MCP server setup