Troubleshooting
Relevant source files
The following files were used as context for generating this wiki page:
This page provides technical guidance for diagnosing and resolving issues within the @pcstyle/auth SDK. The SDK provides a unified authentication layer for PCSTYLE services using WorkOS AuthKit, integrating with Next.js and Convex.
Troubleshooting primarily involves verifying environment configurations, middleware path matching, and hook usage within the correct React contexts.
Configuration and Environment Issues
Most integration issues stem from missing or mismatched environment variables required by the WorkOS AuthKit and the PCSTYLE unified auth domain.
Environment Variable Requirements
The SDK relies on specific environment variables to maintain session consistency across the *.pcstyle.dev ecosystem.
| Variable | Requirement | Impact if Missing/Incorrect |
|---|---|---|
WORKOS_API_KEY | Required (sk_...) | Server-side authentication requests will fail. |
WORKOS_CLIENT_ID | Required (client_...) | OAuth flows and Convex JWT validation will fail. |
WORKOS_COOKIE_PASSWORD | 32+ characters | Session decryption will fail; must match across all subdomains. |
WORKOS_COOKIE_DOMAIN | .pcstyle.dev | Cross-subdomain authentication will not function. |
Sources: README.md:12-17, src/types.ts:79-82
Cross-Subdomain Session Failures
If users are signed in on one subdomain (e.g., auth.pcstyle.dev) but appear unauthenticated on another, ensure the WORKOS_COOKIE_PASSWORD is identical across all services and the WORKOS_COOKIE_DOMAIN is explicitly set to .pcstyle.dev.
Sources: README.md:19, src/types.ts:80-82
Middleware and Routing Issues
Issues in middleware typically manifest as infinite redirect loops or protected routes being accessible to unauthenticated users.
Path Matcher Configuration
The createAuthMiddleware function wraps authkitMiddleware. If the Next.js config.matcher is not correctly defined, the middleware may not execute for protected routes.
The diagram shows the logic flow for request filtering in the authentication middleware.
Sources: src/middleware.ts:1-36
Public Path Exceptions
If a route should be public but triggers a redirect, verify it is included in the publicPaths array passed to createAuthMiddleware.
// Example of correct public path configuration
export default createAuthMiddleware({
publicPaths: ['/api/health', '/public'],
});
Sources: src/middleware.ts:18-24, src/types.ts:35-39
Hook and Component Errors
Context Errors (useUser)
The useUser() hook is designed to throw an error if called in a context where a user is not authenticated.
The sequence diagram illustrates the internal validation logic of the useUser hook.
Sources: src/hooks.ts:36-46
Loading States
If the UI flickers or shows unauthenticated content briefly, ensure the isLoading property from useAuth() is being handled before checking isAuthenticated.
Sources: src/hooks.ts:22-26, src/types.ts:24-28
Convex Integration Issues
JWT Validation Failures
The Convex integration depends on a customJwt provider. If Convex cannot verify the WorkOS token, verify that the WORKOS_CLIENT_ID passed to createConvexAuthConfig is correct.
// src/convex.ts
export function createConvexAuthConfig(clientId: string | undefined) {
if (!clientId) {
throw new Error('WORKOS_CLIENT_ID is required for Convex auth config');
}
// ... returns providers for https://api.workos.com/
}
Sources: src/convex.ts:11-34
Summary
Troubleshooting the @pcstyle/auth SDK involves validating the environment (specifically cookie domains and passwords), ensuring the Next.js middleware matcher covers the intended routes, and correctly handling the loading and error states provided by the useAuth and useUser hooks. Always verify that the AuthKitProvider from @workos-inc/authkit-nextjs/components is present in the root layout to provide the necessary context for client-side hooks.
Sources: README.md:38-48, src/hooks.ts:1-28