> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kordless.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common problems, what they mean, and how to resolve them.

Every surface state in Kordless is designed to be recoverable. When something is wrong, the interface shows you what happened and offers the one legitimate next step — never a blank screen or a dead end.

## Surface states you may see

Each module can render one of several states instead of its normal content. Here is what each means and what to do:

### "You don't have access"

You are signed in as a member, but this operation requires an admin. Ask an organization admin to perform the action or grant you admin role in Clerk.

**Common when:** Managing billing, minting API keys, configuring webhooks, or starting Stripe Connect onboarding.

### "Not included on this plan"

The feature is not available on your current plan tier. Review your plan on the Usage & billing page.

**Common when:** A Sandbox workspace tries to use Live features, or a Pro workspace tries to use Scale portfolio controls.

### "Live use is paused"

The workspace is on the Pause plan or the subscription is past due. Execution is stopped; all data is preserved. Resume by switching back to a paid plan or updating your payment method.

**Common when:** You paused Live use, or a payment failed.

### "No environment"

The workspace has no active Test or Live environment for the mode you switched to. Switch modes or open your workspace.

**Common when:** You switched to Live mode but the workspace has no Live environment binding yet.

### "Not set up" (empty state)

The feature is available on your plan but has not been configured yet. The empty state tells you what will appear and offers the next real action.

**Common when:** Commitments are available but booking has not been enabled, or the Book has not been created yet.

## Book problems

### Extraction failed

You uploaded a pricing source, but Kordless could not read it.

**What happens:** The source is preserved — it was accepted. The extraction error detail is surfaced. The workspace stays in the extracting state.

**What to do:**

* **Retry** — The extraction may succeed on a second attempt.
* **Replace the source** — Upload a clearer or different format.
* **Try another starting method** — If the workspace has other accepted sources, continue with those. Or switch to guided setup, explain how you quote, or start from a supported starting point.

### Book is blocked

The compiler reports blocking issues that prevent publication.

**What happens:** The Book state shows `blocked`. The blocking issues are listed on the Book home.

**What to do:** Resolve each blocking issue listed. The issues are specific — for example, a statement that references a service that no longer exists, or a rule with a missing required input. Once all blocking issues are resolved, the Book returns to its previous state and you can publish.

### Publish partially failed

Publication started but did not complete cleanly.

**What happens:**

* If nothing committed, the **prior Live version remains authoritative**. Retry the publish — it is idempotent.
* If a new version committed but the workspace did not freeze, the publish **completes from the partial state**. The new version is authoritative.

**What to do:** Retry the publish. The operation is idempotent — a partial commit completes from where it left off, and a fully committed publish reports "no action needed."

### Session ended during setup

You left during clarification, calibration, or verification and came back later.

**What happens:** You resume from the earliest unresolved gate. Completed decisions are not repeated.

**What to do:** The Book home shows your next action:

* If there are open required questions → answer them.
* If there are undecided calibration cases → review them.
* If there are unverified statements → verify them.
* If everything is verified → publish.

## Quote problems

### Quote returned "needs input"

The evaluator could not produce a price because required information was missing.

**What happens:** The quote appears in the "Needs input" bucket on the Quotes work list.

**What to do:** Open the quote and provide the missing information. The evaluator will re-run once the inputs are complete.

### Quote returned "unavailable"

The evaluator determined the request is outside the Book's coverage or stop conditions triggered.

**What happens:** The quote appears with an `unavailable` outcome. This is a legitimate product outcome — the system did not guess.

**What to do:** Review why the evaluator returned unavailable. If the work should be covered, add the service or adjust the stop conditions in the Book. If the work is genuinely unsupported, the outcome is correct.

### Quote returned "failed"

The evaluator encountered an error.

**What happens:** The quote appears with a `failed` outcome. The error is recorded.

**What to do:** Retry the quote. If the failure persists, the error detail on the quote receipt explains what went wrong.

## API problems

### API key not working

Requests return `401 Unauthorized`.

**Check:**

* **Environment** — Test keys (`sk_test_…`) cannot address Live. Live keys (`sk_live_…`) cannot address Test. Make sure the key matches the environment you are calling.
* **Status** — The key may be revoked or past its grace period after a rotation. Check the key status on the Developers page.
* **Scopes** — The key may not have the required scope for the operation. For example, producing quotes requires the `quotes:write` scope.

### Webhook not receiving events

Your endpoint is not getting delivery attempts.

**Check:**

* **Endpoint URL** — Verify the URL is correct and reachable from the public internet.
* **Secret** — The `X-Kordless-Signature` header must be verified against the endpoint's current secret. If you rolled the secret, update your verification code.
* **Events** — Webhooks deliver commitment events. If no commitments have been created, no events will fire.

## Billing problems

### "There is no Studio subscription to pause"

You tried to pause but there is no active paid subscription to pause from.

**What to do:** Pause is a transition from an active paid plan. If you have no subscription yet, start a checkout instead. If your subscription was already canceled, start a new subscription.

### Plan change shows "Already on this plan"

You tried to switch to the plan you are already on.

**What to do:** No action needed — you are already on the target plan.

### Subscription is past due

A payment failed and Stripe marked the subscription as past due.

**What happens:** Execution stops. All surfaces show the paused state. Data is preserved.

**What to do:** Update your payment method in the Stripe portal. Once Stripe processes the payment, execution resumes automatically.

## Domain problems

### Custom domain not resolving

You connected a custom domain but it is not serving your site.

**Check:**

* **DNS verification** — Confirm the DNS records have propagated. DNS changes can take up to 48 hours, though most resolve within minutes.
* **Domain ownership** — The domain must be verified before it goes live. Check the verification status in Settings under Customer surfaces.

### Subdomain rename failed

You tried to rename your subdomain but received an error.

**Check:**

* **Availability** — The name may be taken, reserved, or in another workspace's grace window. The availability check tells you which.
* **Cooldown** — Subdomain renames are rate-limited to once every 30 days. The error includes when you can rename again.
* **Characters** — Only letters, digits, and hyphens are allowed. Names must be at least three characters and cannot start with `xn--`.

## Still stuck

If none of these resolve your issue:

1. **Check the environment indicator** — Make sure you are in the right mode (Test or Live). Many issues come from being in the wrong environment.
2. **Check your role** — If you are a member, some operations require an admin. Ask your organization admin.
3. **Check the Book state** — The Book home always surfaces the single next action. If the Book is blocked, paused, or needs attention, that is your starting point.
4. **Check request logs** — If you are debugging an API integration, the Developers page has a request log showing every `/v1` request with method, path, status, and timing.