Troubleshooting & FAQ

Destructive-call refusal

MolarDestructiveCallError

Symptom: Test fails before any HTTP request with "Molar refused destructive call to https://api.stripe.com/..."

Cause: Your app still points at a live vendor host with a key that matches live patterns (sk_live_, production Twilio SID, etc.).

Fix:

1. Set vendor base URL to the clone: STRIPE_API_BASE, MOLAR_CLONE_STRIPE_URL, or SDK clone.url
2. Use clone.testKey instead of a live secret
3. Verify the route proxy is in path if using transparent interception

Escape hatch (intentional live call only):

export MOLAR_DESTRUCTIVE_ALLOW=1

Never set this in CI.

MolarUnknownTargetError

Symptom: "Expected X-Molar-Clone response header"

Cause: URL points to something that is not a Molar clone (misconfigured BYOC URL, stale load balancer).

Fix:

1. curl -I {url}/t/{runId}/_clone/health — expect X-Molar-Clone: stripe@...
2. Register correct BYOC endpoint in Fleet
3. Enable strict mode only after fleet is verified

SDK / runtime errors

MOLAR_E020: @molar/clones is not installed

npm install @molar/clones

Or remove clone declarations from .molar.md if clones are not needed.

MOLAR_E021: clone "stripe" was not started

Add the kind to scenario frontmatter clones: array. The compiler must emit molar.clones.start([...]) in beforeAll.

MOLAR_E022: unknown clone kind

Check spelling against supported vendors. Fixture kinds use the same names as the catalog (github, not gh).

MOLAR_E023: waitForEvent not supported

Use expectWebhookFired on stripe, or admin poll for other kinds.

Clone won't start locally

clone did not become ready

1. Check port conflicts — library mode picks random free ports
2. Read stderr from child process (logged on timeout)
3. Verify Go binary: go run ./cmd/clones-stripe with explicit MOLAR_CLONE_ADDR
4. On Apple Silicon, use arm64 release binaries

Binary not found

export MOLAR_CLONE_STRIPE_BIN=$(which clones-stripe)
# or
npm install @molar/clones-core  # triggers postinstall binary fetch

501 Not Implemented

Symptom: Vendor API returns HTTP 501 for a specific path.

Cause: Endpoint not yet inAPI coverage for this clone kind.

Workaround:

1. Check per-vendor guide for coverage table
2. Log appears in dashboard explorer 501 log
3. Submit request via Developers → 501 request form

501s do not indicate misconfiguration — they indicate a spec gap.

Webhook not received

1. Confirm webhook endpoint registered in clone (Stripe /v1/webhook_endpoints)
2. Check Run workspace → Webhook inspector for delivery attempts
3. Increase timeout: expectWebhookFired("event.type", 60_000)
4. Advance clock if event is time-dependent (invoice finalize)
5. Verify signature secret matches HKDF(seed, "webhook-secret")

Snapshot restore failed

1. Check schema version compatibility (_schema field)
2. Ensure restore targets same runId as save
3. World restore: confirm all kinds in manifest are registered and healthy
4. Large snapshots: check retention quota (default 100 MB per snapshot)

During restore, clone may return 503 while state is loading.

Quota exceeded (HTTP 429)

Symptom: Quota Exceeded with resource: concurrent_clones

Fix:

1. Teardown idle sessions in Sessions
2. Reduce parallel CI matrix jobs
3. Contact support@molar.it to raise limits

Daily quotas reset at 00:00 UTC. See Error codes.

Clock / timing issues

Subscription didn't renew after advanceClock

• Advance past current_period_end shown on subscription object
• Stripe test-clock rate limits don't apply to clones, but verify duration string (30d not 30)

OTP expired too early/late

• Twilio Verify TTL is clock-driven — use advanceClock not setTimeout in tests

On-prem / Helm

Full runbook: molar-clones/docs/onprem-runbook.md

FAQ

Is the Auth clone the same as Molar dashboard login?

No. The Auth clone simulates Clerk for your application under test. Molar operators sign in with Better Auth at app.molar.it.

Can I hit real Stripe test mode and Clones together?

Not in the same test without MOLAR_DESTRUCTIVE_ALLOW=1. Clones are designed to fully replace vendor sandboxes for hermetic runs.

Do fixture clones support world snapshots?

Not today. World snapshots cover the five deep clones only.

What's the difference between email and sendgrid in the catalog?

Same binary. sendgrid is the registry name; SDK and .molar.md use email.

How do Guard PR runs get clone URLs?

Guard spawns fresh sessions via the Molar API and injects env vars into the CI job. Failed runs link to the Clones session workspace.

Are webhook signatures identical to production?

Molar uses the same algorithms and header formats as Stripe, Twilio, and Svix (Clerk/Resend). A golden signer corpus runs in CI for fixed test vectors; vendor webhook signatures are verified in CI.

Can agents spawn clones without the dashboard?

Yes — via MCP molar_clone_spawn with OAuth or API key auth.

Where is the OpenAPI spec?

molar-clones/docs/openapi/control-plane.json and dashboard Developers hub.

Getting help

Include: runId, clone kind(s), seed, dashboard session URL, and relevant log export from Run workspace.