Slab5Documentation

Troubleshooting

Most Slab5 quickstart failures fall into five categories: endpoint values, credential type, scopes/modules, workspace state, or billing/limit state. Start with the request ID and the credential type, then narrow from there.

Debugging model

Use this order:

  1. Confirm the command is using the expected environment variables.
  2. Confirm the API or MCP endpoint is reachable.
  3. Confirm the credential type matches the surface.
  4. Confirm required scopes and workspace module enablement.
  5. Use request_id to find matching logs, audit events, and usage events.

Personal workspace

Common failures:

  • The account did not receive a personal workspace.
  • The command uses a production endpoint with a personal workspace token, or the reverse.
  • The workspace slug or workspace header points at the wrong workspace.
  • The module needed by the route or tool is not enabled in the personal workspace.
  • The personal workspace has exhausted testing quota or is paused.

REST auth

Use the API key for REST:

REST workspace checkbash
curl "$SLAB5_API_BASE_URL/workspace" \
  -H "Authorization: Bearer $SLAB5_WORKSPACE_API_KEY"

Common failures:

  • unauthorized: missing bearer token, malformed header, revoked/expired API key, or wrong secret.
  • missing_required_scope: the API key exists but does not include the route scope.
  • module_not_enabled: the workspace does not have the required module enabled.
  • resource_not_found: wrong route, missing /v1, or wrong API base URL.
  • MCP token used against REST API route.

MCP auth

Use the MCP token for MCP:

MCP tools checkbash
curl -X POST "$SLAB5_MCP_URL" \
  -H "Authorization: Bearer $SLAB5_WORKSPACE_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "tools-1",
    "method": "tools/list"
  }'

Common failures:

  • unauthorized: missing bearer token, revoked/expired MCP token, wrong secret, or OAuth token rejected.
  • Static token rejected because workspace MCP auth policy is OAuth-only.
  • OAuth token rejected because workspace MCP auth policy is static-token-only.
  • OAuth request cannot resolve an active workspace membership.
  • OAuth request made to the bare /v1 address without naming a workspace.
  • Static token used against another workspace's URL: This credential is not valid for workspace <slug>.
  • API key used against MCP route.

Hosted OAuth MCP

For production OAuth setup, confirm the copied server URL keeps the /v1 base path and names a workspace:

https://mcp.slab5.com/v1/w/your-workspace-slug

The protected-resource metadata URL keeps /v1 and names no workspace:

https://mcp.slab5.com/v1/.well-known/oauth-protected-resource

If the connection fails at the callback with invalid_target, the client sent a resource identifier the authorization server does not recognise. The usual cause is a workspace added to the metadata URL or to the resource parameter: there is one protected resource for the whole server, https://mcp.slab5.com/v1, and per-workspace identifiers are not registered.

If a client reports no tools available after a successful sign-in, the tool listing is empty or the request never reached the gateway. Check, in this order:

  • The URL names the workspace you meant, spelled as its slug.
  • The signed-in user has active membership in that workspace. Membership in a different workspace of the same account is not enough.
  • The workspace MCP auth policy allows OAuth.
  • Any explicit OAuth workspace grant for that subject includes the required scopes.
  • The required modules are enabled for the workspace — a tool whose module is disabled is withheld from tools/list, not just refused on call.

A tools/list that succeeds but returns fewer tools than expected is scope or module filtering; a client that shows nothing at all more often means the request was rejected before the listing ran.

If ChatGPT shows Output schema recommended, refresh or reconnect the MCP server after confirming tools/list returns outputSchema for each tool.

Scopes and modules

Every REST route and MCP tool checks both:

  • credential or membership scopes
  • workspace module enablement

Fix missing scope by creating a credential with the required scope. Fix disabled module errors by enabling the module for the workspace. Do not bypass these checks in local tests; they are core tenant-isolation and authorization behavior.

Billing and limits

Billing errors can block billable REST, MCP, storage, webhook, workspace, credential, or high-volume operations.

Expected safety behavior:

  • Login stays available.
  • Billing settings stay available.
  • Usage visibility stays available.
  • Credential revocation stays available.
  • Data reduction paths stay available.

If the quickstart unexpectedly receives a billing pause error, inspect the billing account, usage balance ledger, entitlement overrides, and usage event that corresponds to the request ID.

Webhooks

Common webhook issues:

  • Provider webhook missing signature.
  • Provider webhook signature invalid.
  • Duplicate provider event already processed.
  • Slab5 webhook endpoint is paused or disabled.
  • Delivery is still pending because the outbound worker has not run yet.
  • Delivery is retrying because the receiver returned a non-2xx response or the request failed.
  • Retry state reached failed after max_attempts.

For Slab5 outbound webhooks, verify the receiver is reachable over HTTPS, accepts POST JSON, and validates the x-slab5-signature header against the exact raw JSON body. The delivery log shows the latest status code, error excerpt, attempt count, and next retry time.

What to include in a support report

Include:

  • request ID
  • timestamp and timezone
  • route or MCP tool
  • HTTP status and stable error code
  • workspace slug
  • credential prefix, not the secret
  • whether the credential is an API key, static MCP token, WorkOS API key grant, or OAuth token
  • whether the issue happens in a personal workspace, shared workspace, or production workspace

Was this page helpful?