BuildBaseBuildBase

Troubleshooting

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

Authentication

Sign-in button does nothing

  • 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.

Social login redirect fails

  • 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.

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.
  • User needs Permission.WORKSPACE_MEMBERS_INVITE permission.

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