Troubleshooting

Solutions for common issues with authentication, workspaces, billing, and permissions.

Looking up a specific error code or message? See Error codes.

Start here

Most reports come down to one of three things: the provider is not mounted above the component, the session is not persisting, or a permission is missing. Drop this in the page that misbehaves - it separates those three in one render.

import {
  usePermissions,
  useSaaSAuth,
  useSaaSWorkspaces,
} from '@buildbase/sdk/react';

export function BuildBaseDiagnostics() {
  const { isLoading, isAuthenticated, user, session } = useSaaSAuth();
  const { role, isOwner } = usePermissions();
  const { workspaces } = useSaaSWorkspaces();

  return (
    <pre>
      {JSON.stringify(
        {
          isLoading,
          isAuthenticated,
          userId: user?.id ?? null,
          hasSession: Boolean(session),
          role,
          isOwner,
          workspaceCount: workspaces?.length ?? 0,
        },
        null,
        2
      )}
    </pre>
  );
}

Read it like this:

What you see	What it means
The component throws on render	It is outside `SaaSOSProvider` - mount the provider higher
`isLoading` never becomes `false`	The session callback is not resolving. Return `null` explicitly for "no session" rather than leaving it pending
`isAuthenticated: false` with `hasSession: true`	The session ID is reaching the SDK but is not valid - usually expired, or from a different org
`isAuthenticated: true`, `workspaceCount: 0`	Auth is fine; the problem is workspace scope, not sign-in
`role: null` on an authenticated user	The user is not a member of the active workspace

To check the API directly, without the SDK in the way:

curl -i https://api.console.buildbase.app/api/workspaces \
  -H "Authorization: $BUILDBASE_TOKEN"

A 401 here means the credential is wrong. Note the body is plain text, not JSON - see the admin API for the error shapes.

Authentication

Verify auth.clientId in your SaaSOSProvider matches the client ID in the BuildBase dashboard.
Check that your redirect URL matches what's configured on your client in User management > Access > Authentication.
Open browser DevTools > Network tab and look for failed requests.

User stuck in loading state

useSaaSAuth() returns isLoading: true until the session is resolved.
Check that your getSession callback returns the stored session ID (or null).
If using cookies, ensure the cookie name matches what your backend sets.

"Unauthenticated" after page refresh

Session ID must persist across page loads. Store it in a cookie or localStorage.
Check that your getSession callback reads from the correct storage.
Sessions last 30 days. If expired, the user must sign in again.

Verify the OAuth callback URL in the provider's developer console matches your redirect URL.
Check that the provider's client ID and secret are correct in the dashboard auth methods.
See Social Providers for the callback URL each provider needs, and what each reason on the returned URL means.

Workspaces

No workspaces returned

By default, a workspace is auto-created on the user's first request.
Check that the user's session is valid - workspace data requires authentication.

Workspace switcher shows empty

useSaaSWorkspaces() must be called within SaaSOSProvider.
If workspaces is empty, the user has no workspaces yet.

Can't invite members

If seat pricing is enabled, check useSeatStatus().canInvite - may be blocked at the seat limit. Pending invitations hold seats too; revoke one to make room.
User needs Permission.WORKSPACE_MEMBERS_INVITE permission.
The address has no account yet: that is what inviteMember is for. addUser answers 404 for it on purpose. They will get an email; the row appears under the invite form until they accept.
A 503 on invite means the organization has no usable email sender. Add one in the console under Emails.
A 400 naming landingUrl means the auth client the inviter signed in through has no allowed redirect URL for the link to land on. Add one under Authentication, or pass landingUrl.

The invitation link opens the app but nothing happens

The link must land on an allowed redirect URL of the auth client, which is where SaaSOSProvider is mounted. The SDK reads ?bb=action:invite,token:… on that page and parks the token for a day.
If the user registers and takes longer than ten minutes to verify their email, the hosted sign-in's return URL is dropped; the parked token still resumes the flow on return. Failing that, useMyInvitations() lists what is waiting by email.
Accepting answers EMAIL_NOT_VERIFIED: the accept carried no link token, so the server required a verified account. The SDK's own landing passes the token for you; a custom landing must pass it to acceptInvitation(id, { token }).
The link carries the invitation token in the query string, like a magic link. The SDK replaces the URL before any navigation, but the first document load can still send it in Referer to third-party resources on that page. Serve the landing page with Referrer-Policy: strict-origin-when-cross-origin (the Next.js default) or stricter.

Billing & Subscriptions

`useSubscription()` returns null

The workspace has no active subscription. This is the default state.
Check that at least one plan version is published in the dashboard.

Checkout fails

Verify the plan version has pricing configured with valid Stripe price IDs in the dashboard.

Trial not starting

Trials must be enabled on the plan version in the dashboard.
Each workspace can only trial once.

Credits & Quotas

`useCreditBalance()` returns null or 0

No credits have been granted to this workspace. Credits come from plan grants, admin grants, or credit package purchases.
If no credit packages exist in the dashboard, CreditStorePage will be empty.

`useConsumeCredits()` throws INSUFFICIENT_CREDITS

The workspace has fewer credits than requested. Check balance.available.
The error includes available and requested fields for display.

Quota recording fails with "Quota not found"

The quota slug doesn't match any quota on the workspace's current plan version.
Quotas must be configured on the plan in the dashboard.
If the workspace has no subscription, usage recording fails.

Permissions

`can()` returns false for everything

The user is not the workspace owner and no permissions are configured.
Default: owner gets all permissions, others get none.
Configure role permissions in the dashboard or pass defaultPermissions to SaaSOSProvider.

Permission changes not taking effect

Permissions refresh hourly. For immediate effect, sign out and back in.

Feature Flags

`WhenWorkspaceFeatureEnabled` never renders

The feature slug must match exactly (case-sensitive).
Check that the feature is enabled for this workspace's plan in the dashboard.

SDK Setup

"Module not found" on import

Verify @buildbase/sdk is installed: npm list @buildbase/sdk.
React imports use @buildbase/sdk/react, not @buildbase/sdk.
Server imports use @buildbase/sdk (default export).

TypeScript errors on hook return types

Ensure you're using TypeScript 5.0+.
Run npm install @buildbase/sdk@latest for the latest type definitions.

Provider throws "Invalid config"

serverUrl must be a valid URL (including protocol).
orgId must be a 24-character hex string from the dashboard.

Getting Help

Email: [email protected]
Documentation: docs.buildbase.app
SDK Reference: See the SDK README for the full API reference.