> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Troubleshoot Your First Operation
> Find the blocked step in signup, MCP access, agent setup, workflow trials, and live dispatch without repeating uncertain writes.
Start at the first result you cannot verify. A workspace can exist while its connector is
unhealthy; an agent can answer while a workflow has never received an event. Diagnose those
boundaries separately.
This guide covers the [platform onboarding path](/guides/platform-onboarding), Response MCP,
and the Workstream trial. For native-library installation or local commerce data, use
[SDK installation](/guides/sdk-installation) and [Your First Operation](/guides/first-operation).
## Find your stopping point
Signed in, but cannot reach the intended organization? Check selection and membership.
Check the endpoint, accepted credential type, and resolved secret.
Check discovery, scopes, and the actual tenant exposed by your connection.
Inspect saved settings, processed knowledge, and the failed test.
Follow the accepted job through its steps and workflow execution.
Separate dry runs, routing, review decisions, and dispatch evidence.
## Workspace access
Open [Response Setup](https://response.stateset.com/setup) and confirm the selected organization.
If signup did not complete, finish the sign-in, organization, or plan step the app displays.
If your organization already exists, resolve membership rather than creating another workspace.
For portal provisioning, inspect the existing launch/verification results. Use **Open your
Response workspace** after launch. A partially provisioned service needs its reported issue
resolved; another signup is not evidence that the original workspace has been repaired.
If the workflow UI reports that the organization is not mapped to the engine, ask the workspace
administrator to check the organization-to-brand mapping. The Response organization ID,
Workstream brand UUID, and brand slug are not interchangeable.
**Recovered when:** the intended workspace opens and a read shows the expected organization or
brand, without creating duplicate records.
## MCP connection
Check the exact remote endpoint:
* Response: `https://response.stateset.com/api/mcp`
* Workstream: `https://api.workstream.stateset.com/v1/mcp`
Use the supported authentication path for that server. A browser session does not automatically
supply credentials to an external MCP host, and one service's API key need not work on another.
If configuration contains an environment-variable placeholder, verify your host resolves it.
| Observation | Interpretation and next step |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401` | Check key type, revocation/rotation, secret substitution, and deployment support. If an accepted workspace-key setup still fails, the operator may need to check issuer configuration |
| Response `503` with JSON-RPC `auth_unavailable` | Workspace-key verification is unavailable; have the service operator inspect that dependency. This does not establish that the customer's key is invalid |
| HTTP `404` | Check the full endpoint path and deployed service; do not substitute a REST route for MCP |
| Host cannot launch a process | Check stdio command, installed runtime, and absolute paths; a remote URL is not an executable |
| Connects but reads the wrong data | Stop writes and correct the tenant or local database connection |
The Response workspace-key unavailable path can return `Retry-After`. Respect it for a later
connection/read attempt. Do not apply this advice as a blanket retry rule for business writes.
See [service error contracts](/api-reference/errors-across-engines).
**Recovered when:** discovery succeeds and a read identifies the intended data source. Avoid
rotating every credential or disabling authentication to diagnose one failing connection.
## Missing tools
Refresh `tools/list` in the host and inspect the actual input schema. A missing tool can reflect
credential scopes, a selected profile, a deployment version, or a transport limitation.
Response's `test_agent` and evaluation runs require generation/write permission, even though
your purpose is testing. Reading an agent successfully does not establish that permission.
Some Workstream tools delegate to REST handlers and require HTTP transport rather than local
`mcp-stdio`.
Do not invent a tool name or bypass a denial with another tenant ID. Ask the administrator for
the permission needed for the specific task, then verify discovery and access again.
**Recovered when:** the required tool is exposed and authorized for the intended record. See
[the connection walkthrough](/guides/manage-platform-with-mcp#2-verify-access-before-requesting-changes).
## Agent behavior
Find the existing agent before creating a replacement. Inspect its saved instructions,
settings, rules, and sources using the app or the supported Response reads.
* A newly imported source must finish processing before you treat it as searchable knowledge.
* An imported policy is not live order data. Order questions need the configured lookup.
* A test question must exercise the intended agent, not an assumed default agent.
* A correction stored as an evaluation does not itself change the agent's behavior.
Rerun the narrow failing case after an authorized correction. Preserve the response/evaluation
ID and the expected answer. `run_eval` returning `passed: null` means grading could not run;
resolve that before calling the test passed. A capped suite with `has_more` is incomplete.
**Recovered when:** the saved change is visible and the relevant test has an observed, reviewed
result. Use [the first-week evaluation loop](/guides/first-week-with-stateset#turn-a-correction-into-a-regression-case).
## Workflow trial
Keep the existing brand UUID and accelerator job ID. Use `get_onboarding_accelerator_status`
for the latest job on that brand and `get_onboarding_funnel` for the next incomplete milestone.
Compare the returned job ID with the attempt you are investigating; a latest-status read is
not a request for an arbitrary historical job.
Inspect every step, including `skipped` reasons. A job response or a completed report does not
mean all dependent operations succeeded.
| Step or symptom | What to inspect | Who can resolve it |
| ------------------------------------------ | ----------------------------------------------------------------------- | -------------------------------------------------------------------- |
| Discovery/harvest lacks credentials | Whether Gorgias is connected through the supported credential flow | Workspace connector administrator |
| Provider discovery fails | Provider authorization and refresh errors | Connector administrator |
| Draft step skips an active brand | Expected behavior; the accelerator does not overwrite the active config | Workflow editor, through explicit draft/evaluate/apply |
| Webhook registration is skipped | The reported missing provider input, such as Shopify webhook secret | Connector administrator; provide secrets through the connection flow |
| Activation fails | Readiness details: connector health, config, or billing requirements | Owner of the reported blocker |
| Backfill skips an inactive brand | The activation failure above it | Workflow administrator |
| Job remains running or reports stale state | Job timestamp, worker/API availability, and execution evidence | Service operator; inspect before launching another job |
| Backfill queued but report empty | `list_brand_workflows`, then `get_workflow_run` for relevant runs | Workflow/service operator |
**Recovered when:** a trial report and run evidence show what happened to a replayed ticket.
Do not lower evaluation thresholds or switch routing live just to make an onboarding indicator
turn green.
## Missing replies
Follow the evidence in order:
1. **Event:** did a real provider event reach the brand? A replay does not prove webhook delivery.
2. **Run:** did it execute, skip, fail, or escalate? Read the actual reason.
3. **Mode:** was this a backfill/dry run or shadow operation? Those drafts are not customer sends.
4. **Review:** is the reply waiting for a human decision? Inspect the configured review process.
5. **Dispatch:** did the provider accept the send, and what evidence identifies the resulting message?
Backfill replay uses `dry_run: true` and bypasses the human-review waiting step. No approval
item for that replay is expected. For real traffic, brand activation and live routing are
separate; an active shadow brand still does not establish customer dispatch.
Do not send the reply manually until you have reconciled whether the original dispatch
succeeded. If it is still uncertain, keep the case visible to its owner rather than creating
a second send attempt without evidence.
**Recovered when:** the run and channel evidence agree on whether a reply was sent, skipped,
escalated, or is still pending.
## Ask your assistant for a diagnosis
Replace the bracketed fields and omit IDs you do not have. This is a read-only investigation;
credentials stay in the configured connection.
```text theme={null}
Diagnose my StateSet onboarding problem without changing anything.
Workspace/organization: [identifier]
Response agent: [UUID, if relevant]
Workstream brand: [UUID, if relevant]
Accelerator job or workflow run: [ID, if known]
Last successful step: [what I verified]
Expected next result: [what is missing]
Time window and timezone: [window]
Inspect the exposed tool schemas first. Read the relevant workspace, agent,
onboarding status, funnel, or workflow evidence. Report the last confirmed
success, the earliest blocker, and which operator can resolve it.
Distinguish unknown from failed. Do not create an agent/brand, rerun onboarding,
rotate credentials, change config/routing, or send a customer message.
Return the relevant record/request IDs and a proposed next step for review.
```
## Hand off a useful support report
Use [Report an API problem](/support#report-an-api-problem), adding the setup step, MCP host and
server, tool name, non-secret organization/brand/job IDs, and the last successful read. Include
whether any previous write may already have completed.
Remove keys, authorization headers, and customer message content before sharing. Report the
error code/body as well as HTTP status when available; an MCP tool failure may be represented
inside a protocol response. A timestamped [host report](/api-reference/hosts) is context, not a
live diagnosis of your request.
## Next steps
Return to the [agent walkthrough](/guides/first-support-agent),
[workflow trial](/guides/first-workflow-trial), or
[MCP management guide](/guides/manage-platform-with-mcp) at the recovered step.