Troubleshooting
Find your symptom below for its cause and the fix. Each problem links to the page that covers its area in full.
Local development
| Symptom | Cause | Fix |
|---|---|---|
npm run dev or npm run build stops with "No Firebase project configured" |
The copy has no project set up: Arc CMS ships its environment files with none | Give your project the default alias and run npm run arc:configure -- --project=default --web-config=fetch (see Before the first npm run dev) |
Sign-in fails at localhost, or your data is not there |
The local app talks to another project than you think | Read the Firebase project: line npm run dev prints as it starts. Change the default alias (firebase use --add), or start with ARC_PROJECT=<alias> npm run dev |
A change to a Cloud Function makes no difference in the browser at localhost |
npm run dev has no emulators: the site talks to the real Firebase project it names as it starts, so it calls the deployed functions |
Deploy the function (see Deploy only what changed), then test again. Test functions logic with specs first (see Testing) |
npm run dev stops with "JavaScript heap out of memory" |
Every change to vite.config.ts or a file it imports, such as src/custom/features.ts, restarts the dev server. vite.config.ts frees each old server, but a long session can still run out |
Start it again, or give Node more memory: NODE_OPTIONS=--max-old-space-size=8192 npm run dev |
npm run build stops with "JavaScript heap out of memory" |
The build compiles the whole app for the browser. Core Arc CMS needs well under 2.5 GB of Node's heap, and npm run build allows 8 GB, so an app needs far more code than core to reach it, or the machine has too little memory |
Give the build a bigger heap, which wins over the script's 8 GB: NODE_OPTIONS=--max-old-space-size=12288 npm run build, and the same in front of npm run deploy. The machine needs that much free memory |
npm run dev or npm run build stops with a message that starts "src/custom/features.ts:" |
An unknown feature name, a feature in both lists, or a feature on while one it needs is off | Change the file as the message says (see Feature ids) |
| A new admin page shows the public "Content Not Found" page | File-based routing does not reliably reach the browser's route table for admin pages, so the URL falls through to the public content route. The page answers with HTTP 200, because Hosting serves the app shell for every path, so a status check does not catch it | Add an explicit route for it in src/app/app.routes.ts, like the other admin pages (see Frontend notes) |
| A component keeps showing old data after a row or page state changed in place (an icon, a hidden button) | The app runs without zone.js. An OnPush component whose inputs did not change is not checked again |
Use default change detection for components whose output reads page state or objects changed in place (see Frontend notes) |
Deploys
| Symptom | Cause | Fix |
|---|---|---|
| "Your database is in ..., but the functions run in ..." during a deploy, or every sign-in step takes seconds | The functions run far from the database, so each database call crosses that distance | On an install with no functions deployed yet, the deploy fixes it itself. On a live one, moving is a release of its own (see Regions) |
| "... is marked production. Add --confirm-production=... to deploy it" | A deploy with options, off a terminal, to a project marked production (arc:configure --production=yes) |
If it is the project you mean, add the flag the message names. CI for a staging project should not be marked (see Deploy from CI) |
| After the first CI deploy, the next one says "Your database is in ..., but the functions run in us-central1" | CI recreates arccms.config.json on every run and lost the region a first deploy chose |
Pass --functions-region to arc:configure in the job (see Deploy from CI) |
| On a project's first deploy, the Firestore triggers fail with "Permission denied while using the Eventarc Service Agent" | Google is still giving Eventarc its permissions, minutes after the deploy turned it on | Nothing to change: the deploy waits 5 minutes and retries them. If it still fails, wait a few minutes and run the same deploy again (see A first deploy to a new project) |
On a project's first deploy, onSignInDeleted fails with "Build failed: Build error details not available", and its build log says Repository "gcf-artifacts" not found |
Its build started a few seconds before Cloud Functions created the project's image repository | Nothing to change: the deploy's retry builds it. If a deploy ended before the retry, deploy it alone: npm run deploy -- --only functions:arccms:arccms.onSignInDeleted |
| New functions are missing after a deploy, or the old code is still live | The deploy ran with plain firebase deploy, which uploads the last functions build as it is |
Always deploy with npm run deploy, which builds first (see Deploy) |
| Every browser call to one function fails with HTTP 403, and the answer is an HTML "403 Forbidden" page | The callable was created without public access, for example in a partly failed deploy. Later deploys do not repair it | Run the callable check and its fix (see Check the callables). A JSON PERMISSION_DENIED answer is different: the function ran and refused the caller |
| A named Firestore database appeared in the project's default location | The Firebase CLI creates a missing named database on the first deploy, even with --dry-run, in the default location |
Create the database yourself, in the location you want, before any deploy. npm run arc:configure prints the commands (see Sharing a Firebase project) |
| The deploy stops with a message and deploys nothing | Missing install settings, a database mismatch, no website, a shared bucket, or functions it would delete | See When the deploy stops |
| Published pages are gone after a website deploy | A Hosting deploy uploads only the build. Published content pages are written to Hosting by Cloud Functions | Publish them again: npm run seed:dev or npm run seed:prod (see Publish the static pages) |
| Sign-ups or public pages fail right after a rules deploy | The new rules went out before the functions or website code they depend on | Deploy the functions and the website, or deploy the previous rules again from git (see When the order matters) |
Sign-in and permissions
| Symptom | Cause | Fix |
|---|---|---|
| "New accounts can't be created on this site right now." | Sign-ups are closed in the site's user settings | Open them in Admin, Settings, User Settings (see Sign-in methods) |
| "This account doesn't have access to this site." | The sign-in account exists, but it has no Arc CMS user record, for example a user of another app that shares the sign-in accounts | An admin adds the person in Admin, Users (see Users and roles) |
| "Google sign-in is not turned on for this site." or "Phone sign-in is not turned on for this site." | That method is off in the site's user settings. Phone sign-in also needs the SMS feature | Turn it on in Admin, Settings, User Settings (see Sign-in methods) |
| A person made admin still gets "Missing or insufficient permissions" | The rules read the role from the ID token, which still carries the old role | Reload the page or sign in again: the app refreshes the token's claims when they disagree with the user record (see Roles and claims) |
| A browser read or write fails with "Missing or insufficient permissions" | A security rule refuses it. A query on users that does not filter on the caller's own uid is refused as a whole |
Check the rule for that collection (see Security rules) |
Data, email, search and features
| Symptom | Cause | Fix |
|---|---|---|
| A query fails with "The query requires an index" and a link to the Firebase console | The query needs a composite index the project does not have | Add the index to firestore.indexes.json (in an app, to firestore.app.indexes.json) and deploy it with npm run deploy -- --only firestore:indexes --project default. The console link creates the same index by hand. Indexes take a few minutes to build |
| An email was not sent | Every email is logged, with the reason when it was held back: email turned off or no provider set, a feature's email turned off, an inactive template, a disabled contact, an unsubscribe, or a suppressed address | Open Admin, Email Logs and read the status and reason. Set up the provider in Admin, Settings, Email Settings (see Email engine) |
| Search finds nothing in a collection of your own | The collection is not in functions/src/custom/search-sources.ts, the functions were not deployed after adding it, it is not set up in Admin, Settings, Search, or its existing documents were never indexed |
Add it, deploy every function, set it up, then use Rebuild in Admin, Settings, Search (see Search) |
| A page shows "not found", and a menu item or settings tab is missing | The feature it belongs to is turned off in src/custom/features.ts: the pages of a feature that is off answer with the not-found page |
Turn the feature on, then deploy the functions and the website (see Choose your app's features or Choose your website's features) |
| A function of a feature answers 404, or is missing from the project | The feature is off, so its functions are not in the build, and a deploy of every function deleted them | Turn the feature on and deploy every function |