Skip to main content

Common Issues

Firebase & authentication​

Firebase: Error (auth/invalid-api-key)​

Cause: Wrong or missing VITE_FIREBASE_API_KEY in .env.

Fix: Copy exact values from Firebase Console. Restart dev server after editing .env.

Missing or insufficient permissions on Firestore write​

Cause: Security rules not deployed or user lacks access.

Fix:

firebase deploy --only firestore:rules

Ensure user document exists in users collection with appropriate role.

Login works but sidebar is empty​

Cause: User profile missing or portalAccess: "No".

Fix: Create/update users/{uid} with valid role and portalAccess: "Yes".

Build errors​

TypeScript errors during npm run build​

Cause: Strict TypeScript settings (noUnusedLocals, etc.).

Fix: Resolve reported errors in listed files. Run npx tsc --noEmit locally.

Port 3000 is in use​

Cause: Another process using port 3000.

Fix: Vite auto-selects next port, or change in vite.config.ts:

server: { port: 3001 }

Role permissions​

Save permissions fails silently​

Cause: Firestore rule for settings/rolePermissions not deployed.

Fix:

firebase deploy --only firestore:rules

IT Manager still sees Site Map after disabling​

Cause: Browser cache or permissions not reloaded.

Fix: Hard refresh (Ctrl+Shift+R) or log out and back in.

Site map​

Blank page on Location Site Map​

Cause: Firebase init order issue (historically fixed) or JS error.

Fix: Check browser console. Ensure Firestore rules allow siteMapNodes read.

Could not add zone (historical)​

Zones are derived from departments — do not add zones manually on site map. Edit Departments instead.

Reports & export​

Excel export empty​

Cause: No matching data for selected filters.

Fix: Verify assets/requests exist in Firestore for filter criteria.

Documentation site​

Docusaurus won't start​

cd documentation
rm -rf node_modules
npm install
npm start

Requires Node 18+.

Getting help​

  1. Check browser developer console for errors
  2. Check Firebase Console → Firestore → Usage for denied requests
  3. Open a GitHub Issue with steps to reproduce