Common Issues

This guide covers common problems when using SaaSStinger Lite.

Issues are grouped into:

• Installation problems
• Configuration problems
• Firebase problems
• Development problems
• Runtime problems

Before Troubleshooting

Before investigating an issue, verify:

pnpm install

completed successfully.

Then run:

pnpm tsc --noEmit

and:

pnpm lint

to identify code issues.

Application Does Not Start

Symptoms

Examples:

• Development server fails
• Blank page
• Module errors

Check Dependencies

Remove installed packages:

rm -rf node_modules

Reinstall:

pnpm install

Restart:

pnpm dev

Environment Variable Errors

Symptoms

Examples:

Firebase configuration missing

or:

Authentication failed

Solution

Confirm:

.env.local

exists.

Verify required variables:

NEXT_PUBLIC_FIREBASE_API_KEY=

NEXT_PUBLIC_FIREBASE_PROJECT_ID=

FIREBASE_PROJECT_ID=

FIREBASE_CLIENT_EMAIL=

FIREBASE_PRIVATE_KEY=

Restart the development server after changing environment variables.

Firebase Authentication Problems

User Cannot Login

Check:

1. Firebase Authentication is enabled.
2. The provider is configured.
3. Environment variables match the Firebase project.

User Is Redirected Unexpectedly

Common causes:

• Email verification required
• No workspace exists
• Authentication session expired

Check:

Authentication

        ↓

User Profile

        ↓

Workspace Membership

Workspace Creation Problems

Workspace Creation Fails

Verify:

• User is authenticated
• Firebase Admin configuration is valid
• Firestore permissions allow the operation

Expected flow:

User Registration

        ↓

Email Verification

        ↓

Create Workspace

        ↓

Create OWNER Membership

        ↓

Create Usage Record

Firestore Permission Errors

Error Example

FirebaseError: PERMISSION_DENIED

Common Causes

Missing Authentication

The user is not signed in.

Missing Membership

The user does not have a membership document:

memberships/{membershipId}

Incorrect Role

The operation requires:

OWNER

or:

ADMIN

but the user has:

MEMBER

Debug Checklist

Check:

1. User authentication status.
2. Workspace ID.
3. Membership document.
4. Firestore rules.
5. Emulator state.

Firebase Admin Errors

Symptoms

Examples:

Failed to initialize Firebase Admin

Check Environment Variables

Verify:

FIREBASE_PROJECT_ID=

FIREBASE_CLIENT_EMAIL=

FIREBASE_PRIVATE_KEY=

Private Key Formatting

The private key must preserve line breaks.

Example:

FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"

TypeScript Errors

Symptoms

Example:

Type error: Property does not exist

Solution

Run:

pnpm tsc --noEmit

Fix:

• Missing types
• Incorrect imports
• Invalid function parameters

Build Errors

Symptoms

Example:

Build failed

Check Locally

Run:

pnpm build

Common causes:

• TypeScript errors
• Missing environment variables
• Invalid imports
• Server/client component mismatch

Module Not Found Errors

Example

Cannot find module

Solution

Check:

• File exists
• Import path is correct
• Alias uses:

@/

Example:

import Button from "@/components/ui/button";

Firebase Emulator Issues

Emulator Will Not Start

Check:

firebase --version

Verify Firebase CLI is installed.

Emulator Data Problems

Local emulator data may become outdated.

Reset if necessary:

firebase emulators:start --import=./emulator-data --export-on-exit

Permission Problems After Code Changes

After changing:

• Firestore rules
• Authentication logic
• Membership logic

Restart:

firebase emulators:start

Browser Issues

Cached Authentication State

Try:

• Sign out
• Clear browser storage
• Sign in again

Supported Browsers

Recommended:

• Google Chrome
• Modern Chromium-based browsers

Production Deployment Issues

Before deployment verify:

• Environment variables configured
• Firebase project selected
• Firestore rules deployed
• Production build succeeds

Run:

pnpm build

When Contacting Support

Include:

Environment

Operating system:

Node.js version:

pnpm version:

Browser:

Problem Details

Include:

Expected behavior:

Actual behavior:

Steps to reproduce:

Error message:

Helpful Files

If relevant include:

• Console errors
• Terminal output
• Configuration details (without secrets)

Security Reminder

Never share:

• Firebase private keys
• Service account files
• .env.local
• User credentials

Remove sensitive information before submitting issues.

Related Documentation

• Authentication
• Firebase Setup
• Environment Variables
• Firestore Schema
• API Reference