Authentication Errors

SaaSStinger Lite uses Firebase Authentication for user identity management.

Authentication affects:

• Registration
• Login
• Password reset
• Email verification
• Protected routes
• Workspace access

This guide covers common authentication issues.

Authentication Flow Overview

The normal authentication flow:

User Registration

        ↓

Firebase Authentication Account

        ↓

Email Verification

        ↓

User Profile Creation

        ↓

Workspace Onboarding

        ↓

Dashboard Access

User Cannot Register

Symptoms

Examples:

• Registration fails
• Account is not created
• Error appears after submitting the form

Check Firebase Authentication

Verify:

Firebase Console:

Authentication

    ↓

Sign-in providers

The required provider must be enabled.

Check Environment Variables

Verify:

NEXT_PUBLIC_FIREBASE_API_KEY=

NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=

NEXT_PUBLIC_FIREBASE_PROJECT_ID=

NEXT_PUBLIC_FIREBASE_APP_ID=

Restart the application after changing variables.

Email Verification Problems

User Is Redirected to Verification Page

This is expected behavior when:

• Email verification is required
• The account has not completed verification

Flow:

Login

 ↓

Check Email Verification

 ↓

Verified?

 ├── Yes → Dashboard

 └── No → /auth/verify-email

Verification Email Not Received

Check:

• Spam folder
• Email address accuracy
• Firebase email settings

Login Problems

Invalid Credentials

Possible causes:

• Incorrect email
• Incorrect password
• User account does not exist

Solution:

Use the password reset flow if required.

Authentication State Not Updating

Symptoms

Examples:

• User logged in but dashboard does not load
• User appears logged out after refresh

Check Auth Provider

SaaSStinger Lite manages authentication state through:

src/providers/AuthProvider.tsx

Verify:

• Firebase auth listener is running
• User state updates correctly
• Loading state completes

Protected Route Redirects

Symptoms

User is redirected unexpectedly.

Possible causes:

• User is not authenticated
• Email not verified
• Workspace missing

Access Requirements

Dashboard access requires:

Authenticated User

        +

Verified Email

        +

Workspace Membership

User Has No Workspace

Symptoms

User signs in successfully but cannot access dashboard.

Expected Behavior

New users are redirected to onboarding.

Flow:

Authenticated User

        ↓

Workspace Exists?

        |

        ├── Yes → Dashboard

        |

        └── No → Create Workspace

User Profile Not Created

Symptoms

Authentication succeeds but profile data is missing.

Check

Verify:

users/{userId}

exists in Firestore.

Expected fields:

{
  uid,
  email,
  displayName,
  createdAt,
  updatedAt
}

Firebase Auth Permission Errors

Error Example

FirebaseError: permission-denied

Common Causes

• Incorrect Firebase configuration
• Invalid authentication state
• Firestore rules rejecting profile access

Firebase Admin Authentication Errors

Symptoms

Server-side operations fail.

Examples:

Firebase Admin initialization failed

Check Server Variables

Verify:

FIREBASE_PROJECT_ID=

FIREBASE_CLIENT_EMAIL=

FIREBASE_PRIVATE_KEY=

Session Problems

Symptoms

User is repeatedly asked to log in.

Troubleshooting

Try:

1. Sign out.
2. Clear browser storage.
3. Close browser.
4. Sign in again.

Development Testing

When testing authentication locally:

Use:

firebase emulators:start

Verify:

• Authentication emulator status
• Firestore emulator status
• Application connection

Common Developer Mistakes

Checking Authentication Only on Client

Incorrect:

Client says user is ADMIN

        ↓

Allow operation

Correct:

Server Action

        ↓

Verify user

        ↓

Check membership

        ↓

Perform operation

Security Notes

Never:

• Store passwords manually
• Trust client authentication state alone
• Expose Admin SDK credentials

Always:

• Validate server-side
• Use Firebase Authentication
• Protect Firestore rules

Contact Support

When reporting authentication issues include:

• Authentication error message
• Browser console output
• Firebase configuration status
• Steps to reproduce

Never include:

• Passwords
• Private keys
• .env.local contents

Related Documentation

• Authentication
• Environment Variables
• Firebase Setup
• Firestore Permissions
• Common Issues