Troubleshooting
Most reports arrive as "it doesn't work". The status code and the body of the failure usually say which cause it is, and a tool that is missing is the most common. Fixing a permission denial, a held approval or a mode change needs an administrator on the project.
- Ask for the status code and the complete body, not a paraphrase.
- Find the symptom in the table. A body that is not JSON with an
errorfield means the router answered, not Wexa. - To see what a credential carries, open Settings, then Developer access (
/settings/developer-access), or callGET /v1/whoami. - If the table does not settle it, collect the request, status, body and
lifecycle_idbefore you escalate.
| Symptom | Fix |
|---|---|
| "That tool isn't there" | Check GET /v1/connection-info: a name missing is a typo, a not-configured error is the deployment. |
| Listed, but refused on call | A grant is missing; check GET /v1/whoami. |
403 forbidden | Role or scope: yours to fix. |
404 page not found or 405 | Wrong path or verb: the developer's fix. |
410 endpoint_moved | Retired path: use /mcp/{projectId}. |
401 invalid_token | The credential is bad or revoked. |
429 | Quota: Settings, then Usage & Cost (/settings/usage). |
| Saving context stopped | Mode changed: Settings, then Projects (/settings/projects). |
| Change stuck waiting | Approval held: Actions, then Approvals (/actions/approval-flows). |
Limits
| Limit | Behavior |
|---|---|
tools/list | Lists every registered tool to every authenticated caller, without filtering by grants. |
| Grant refusal | A 200 response carrying an error result at S2:resolve-scope. |
| Held approval | Overdue after 48 hours, expires unanswered after 96. |
| Resume token | Single-use. |
POST /mcp/ with a trailing slash | 404, not 410. |
More details
Who this page is for
Anyone can use this page. Fixing a permission denial, a held approval or a mode change needs an administrator on the project, and the rest are for the developer who sent you the failure.
How it works
Check whether the body is JSON with an error field. If not, the gateway's router answered, not Wexa. Read the error value to route the problem to the person who can fix it, and check what the credential carries with GET /v1/whoami when the failure is about access.
Check what a credential carries
Console: Settings, then Developer access (/settings/developer-access) lists a project's API keys with name, creator, data access, dates, last use and status. It does not show grants. API: GET /v1/whoami returns the caller's identifier, role, scope and grants, and GET /v1/connection-info is unauthenticated and returns the tools array the deployment registered.
curl -sS https://fabric.wexa.ai/v1/whoami -H "Authorization: Bearer $FABRIC_API_KEY"
curl -sS https://fabric.wexa.ai/v1/connection-infoTell the failure shapes apart
| What happened | Status | Body | Who fixes it |
|---|---|---|---|
| Permission denial | 403 | {"error":"forbidden","error_description":"…"} | You: it is a role or scope problem |
| Missing route | 404 | 404 page not found, text/plain | The developer: the path is wrong |
| Retired endpoint | 410 | {"error":"endpoint_moved", …} | The developer: the path was real once |
| Wrong method | 405 | Method Not Allowed, text/plain | The developer: right path, wrong verb |
| No or bad credential | 401 | {"error":"invalid_token"} | The developer, or a revoked key |
Fix a 403, a permission denial
The body is JSON with a sentence that names the rule:
403 {"error":"forbidden","error_description":"API key creation requires an admin role on this project"}
403 {"error":"forbidden","error_description":"changing project mode requires an admin role"}
403 {"error":"forbidden","error_description":"project outside token scope"}A 403 is the only one of the five you can fix. The route exists, the method is right and the credential is valid, but the caller is not allowed. "Requires an admin role" is a role problem and "outside token scope" is a project problem, with different fixes.
Read a 404, a missing route
The body is Go's own plain text, not a Wexa error envelope:
404 page not found
It is text/plain with no error field. If the body is not JSON, the gateway never recognised the path: nothing in Wexa produced that response, the router did. The path is misspelled, or it belongs to a different service.
Read a 410, a retired endpoint
This confuses people most, because it is the only failure that used to be a success.
410 {"error":"endpoint_moved",
"error_description":"This URL no longer works. Each project now has its own MCP connect URL …"}Four paths return it: POST, GET and DELETE on /mcp, and GET on /sse. They are the connect addresses from before projects had their own. The replacement carries the project in the path, /mcp/{projectId}, and you can find it two ways.
In Simple mode, the console's "3 · Connect your agent" panel shows the project's URL. Or build it from mcp.url_template in GET /v1/connection-info. See discovery.
One trap inside the trap: POST /mcp/ with a trailing slash returns 404, not 410. The router will not match an empty project identifier, so it never reaches the retirement handler. A developer who reports "sometimes 410, sometimes 404 on the same URL" has a trailing slash.
Read a 405, a wrong method
405 Method Not Allowed
The body is plain text again. The path is right and the verb is wrong, which confirms the route exists. PUT /v1/apikeys and DELETE /v1/audit/verify both produce it. Every tool is POST /v1/<tool-name> in kebab-case, and everything else is conventional REST: GET for reads, plural collections, sub-paths for actions.
Triage with one question each
- Is the body JSON with an
errorfield? If not,404means the path is unknown and405means the verb is wrong. - Is
errorendpoint_moved? The path is retired. Move to/mcp/{projectId}. - Is
errorforbidden? It is yours to fix. Read the description for role versus scope. - Is
errorinvalid_token? It is the credential, not the path.
Fix "That tool isn't there"
This is the most common report and it is almost never a permissions problem. Every Wexa instance lists every tool, on the REST API, through both SDKs and on the Wexa MCP server, whichever services sit behind it.
What varies is whether a tool can run. A tool whose backing service the deployment has not configured is still listed, and a call to it fails with an error naming what is missing:
<tool> is not configured (no data-service URL)<tool> is not configured (no harness URL)<tool> is not configured (needs the harness and data-service URLs)
It fails that way for everybody, you included, and retrying will not help. The fix is the deployment's configuration.
To diagnose it, read the tools array in GET /v1/connection-info. A name missing from it is not a Wexa tool, usually a typo or a retired name. A name present that answers with the not-configured error is a deployment that lacks the service behind it.
Fix "The tool is listed but it refuses when I call it"
The tool was visibly there a second ago, so this looks like a bug.
tools/list on the Wexa MCP server does not filter by the caller's grants, so every registered tool is listed to every authenticated caller. The grant check happens on the call, and its refusal arrives inside a normal 200 response as an error result:
error (S2:resolve-scope): token missing required grant "…"
"It was in the list" is not evidence the caller was allowed to use it. Check what the credential carries with GET /v1/whoami. See credential management for how grants are decided when a key is minted, and roles and permissions for the role behind them.
Fix "It worked this morning and now it's 429"
Console: Settings, then Usage & Cost (/settings/usage). A 429 with a Retry-After header is a quota refusal, not a fault:
429 Retry-After: 24
{"error":"S3:rate-quota","error_description":"quota exceeded for project proj_d18 (retry after 24s)"}
Read the word before the identifier: project and organization are different problems. The header is a real, computed number of seconds, and a client that honours it recovers at the earliest possible moment. See usage and billing.
Fix "Saving context stopped working"
Console: Settings, then Projects (/settings/projects), then edit the project to see its Context Intelligence setting.
422 {"error":"S4:validate-input",
"error_description":"save-context is only available in Simple/auto mode; this project is in
Advanced/manual mode — use create-ontology (proposal/commit)"}Somebody changed the project's mode. This is the most common consequence of that change, and the refusal names the replacement. API: GET /v1/projects/{projectId}/mode. See project mode.
Fix "My change is stuck waiting for approval"
Console: Actions, then Approvals (/actions/approval-flows), the Approvals Inbox.
A consequential write made with an API key or an SDK session is held by default, and so is a non-administrator's ontology commit in Advanced mode.
The caller gets "status":"pending_approval" with a resume token rather than a result. Nothing is wrong. Somebody has to decide it in the Inbox. A held call is overdue after 48 hours and expires unanswered after 96 hours.
If nobody should have to approve these writes, a project admin can turn the gate off in Settings, then Projects.
Three related reports have different causes:
resume rejected: approval not approved (not approved, already used, or not yours): the approval is still pending, was rejected or has expired, the resume token has already been spent, or it is used by a different user, for a different tool or in a different project. Tokens are single-use, so a retried resume always produces this.resume rejected: approval not found: the token is not a resume token at all.approval is already approved,409: two people decided the same item. The first decision stands.
See approvals.
Fix "Everything from yesterday is gone"
The gateway's audit trail at GET /v1/audit, the policy decision log and the OAuth clients are a live view rather than an archive. They can be emptied, silently and without error. Approvals are stored, and their events are kept in the platform audit trail under Governance, then Audit & Lineage (/governance/audit).
Collect these before escalating
A report with these things can be diagnosed without a second round trip:
- The full request: method, path, and whether a credential was attached.
- The status code and the complete body. The difference between JSON and plain text is half the diagnosis.
- The
lifecycle_idfrom the body, if there is one. It joins the call to its audit events and its policy decision. GET /v1/whoamifrom the same credential: role, scope and grants in one line.GET /v1/connection-infofrom the same gateway: thetoolsarray settles every "capability is missing" question.
More limits
| Behavior | What to expect |
|---|---|
| Not-configured tool | Fails for every caller until the deployment is configured. |
| Audit trail, policy decision log, OAuth clients | A live view, not an archive. Can be emptied silently. |
Related
- Errors and retries: what each SDK raises for these failures and which are worth retrying.
- Usage, quota and billing: ceilings, the
Retry-Afterheader and credits.