Slab5

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.
  • API key used against MCP route.

Hosted OAuth MCP

For production OAuth setup, confirm the copied server URL includes the /v1 base path:

https://mcp.slab5.com/v1?workspace_id=...

The protected-resource metadata URL should also include /v1:

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

If a hosted client can sign in but cannot call tools, check:

  • The workspace ID or slug in the URL points to the intended workspace.
  • The signed-in user has active membership in that workspace.
  • 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.

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?