Troubleshooting & FAQ

Answers to the most common Guard questions. Still stuck? Email support@molar.it or see docs.molar.it/support.

Product help: guard.molar.it

General

What does Guard cover that PR checks alone don't?

Guard runs the same scenario file on PR (with affected selection + Clones), production (synthetics), and shadow-prod (vendor drift), then feeds failures to Mender for fix PRs against your application code. See What is Molar Guard?.

Do I need Cartographer or Clones to use Guard?

No. Guard is plug-and-play with any Playwright suite via the CLI (molar-guard run / list) or a registered scenario in the GitHub Action. Cartographer and Clones are optional enrichments.

Where is the dashboard?

• Hosted: app.molar.it/dashboard/guard
• Product info: guard.molar.it
• Local dev: http://localhost:3000 after pnpm dev

PR gating

The Check Run never appears

1. Confirm the GitHub App is installed on the repository (Settings → GitHub in dashboard).
2. Check GitHub Webhook deliveries for api.molar.it — expect 200 responses.
3. Verify GH_APP_ID and GH_WEBHOOK_SECRET are set on the Guard API (self-hosted).
4. Ensure the PR event is not from a draft you haven't marked ready (Guard listens to ready_for_review).

Check stuck on "queued" or "in progress"

• Worker not running: pnpm --filter @molar/guard-worker dev locally; check VM worker health in production.
• Redis down: curl localhost:4000/readyz should show Redis healthy.
• Queue backlog: noisy neighbor on shared infra — contact support for dedicated worker pool (Business tier).

Full suite runs on every small PR

Guard fell back to affected detection safety net:

• 0 scenarios selected on large diff → full suite + guard.affected_fallback metric
• >50 scenarios selected → full suite

Fix: Refresh scenario graph (push to default branch triggers Cartographer graph-only mode). Inspect:

molar-guard affected --base $BASE --head $HEAD

Check passes but production is broken

Your scenario catalog has a coverage gap. Add a scenario for the failing flow; set cache: never on critical paths.

Advisory mode — merge allowed on failure

Expected during the first 30 days. Promote to required in molar-guard.config.ts or branch protection when ready.

Destructive call blocked in PR

MolarDestructiveCallError: destructive call to real Stripe blocked in PR context

Your test or app hit live api.stripe.com during a PR run with Clones enabled. Point SDK at Clone URL from env (MOLAR_CLONE_STRIPE_URL) or disable Clones for that repo.

GitHub Action

MOLAR_API_KEY invalid

Regenerate key at Settings → API keys. Confirm secret name in GitHub repo settings matches workflow.

Action times out

Increase timeout-minutes (default 20). Large suites may need sharding (Business tier) or affected selection via GitHub App instead of Action-only mode.

scenario-id not found

Create the scenario in the dashboard or import from your repo, then copy its UUID into the workflow scenario-id input. The Action requires a registered scenario — it does not auto-discover Playwright tests yet.

Production monitoring

Cannot enable scheduled check — onboarding blocked

Complete Synthetic safety checklist:

1. Analytics filter acknowledgement (POST /v1/onboarding/analytics-ack)
2. Synthetic middleware installed
3. Preflight audit events in dashboard

Real Stripe charge occurred

Stop schedules immediately (pause all checks). This is a Sev-1:

1. Verify is_synthetic middleware is active on the code path hit
2. Confirm synthetic user has is_synthetic = true in DB
3. Contact support@molar.it with run ID

Incidents not resolving

Auto-resolve requires 2 consecutive successes. Flapping scenarios keep incident open — fix root cause or suppress with reason while investigating.

Analytics polluted by synthetic traffic

Review analytics filter onboarding. Exclude users where is_synthetic is true in both server-side traits and client-side event filters.

Shadow-prod

Too many shadow_diff false positives

• Approve expected vendor change → create snooze rule
• Tune shadowDiffThreshold in alert policy
• Add volatile fields to semantic diff allowlist

Shadow-prod not running

Requires shadow_prod: true on scheduled check and Clones enabled for the scenario.

Mender

Mender did not open a PR

Low confidence / wrong classification

Reject with reason (POST /v1/mender/:id/reject) — feeds model improvement. Set mode to suggestive until merge rate improves.

Mender PR fails Guard on push

Expected occasionally — iterate on the PR manually or reject and let Mender retry (if circuit breaker allows).

Token budget exhausted

Switch to BYOK or raise cap via support (Team/Business).

API & auth

401 Unauthorized

Missing or expired token. Refresh session (dashboard) or regenerate API key (CI).

403 Forbidden

Authenticated but wrong org or insufficient role. Send correct x-org-id header.

429 Quota Exceeded

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

Quota resets 00:00 UTC. Upgrade plan or contact support.

503 unavailable

Transient dependency failure (Postgres/Redis). Retry with backoff.

Full table: Error codes

Webhooks

GitHub deliveries return 4xx

Outbound alert webhook not firing

Verify integration in Settings → Notifications; test with manual incident; confirm endpoint returns 2xx within timeout.

Local development

pnpm migrate fails

Postgres not running: docker compose up -d postgres.

Clones not starting

Set MOLAR_CLONES_ROOT to sibling molar-clones checkout. Requires Go toolchain for go run ./cmd/clones-*.

Health check fails

curl localhost:4000/healthz   # liveness
curl localhost:4000/readyz    # postgres + redis

FAQ — billing & plans

Can I use Guard without the rest of Molar?

Yes — Guard is a standalone SKU with its own dashboard and billing.

What counts as a "PR run" vs "prod run"?

PR runs: run_type = pr. Prod runs: run_type = schedule (and shadow_diff ticks). Manual runs may count against daily quota depending on plan.

Does BYOK affect Mender budget caps?

BYOK bills your upstream LLM provider directly. Molar-hosted caps apply only to molar-managed integration.

FAQ — compliance

Is Guard SOC 2 certified?

SOC 2 Type II report available on request for enterprise customers — email support@molar.it.

Where is data stored?

Molar API: Postgres (region-configurable on Business). Artifacts: S3-compatible object storage. Workers: regional pools (us-east-1, eu-west-1, ap-south-1).

Can I self-host Guard?

Yes — full stack with Docker Compose for local/CI. Contact support@molar.it for air-gapped Helm guidance.

Getting more help

1. Collect run ID, incident ID, or webhook delivery ID
2. Note timestamp (UTC) and org ID
3. Email support@molar.it with reproduction steps

Include curl -v output for API issues (redact API keys).

Related docs

• Quick start
• GitHub App setup
• Security
• Webhooks & API
• Error codes