Guide · Firestore

Firestore won't connect? Common errors and how to fix them

Whether you're using a database tool in your IDE, a script, or your own app, most Cloud Firestore connection failures come down to a handful of causes. Here they are, with the exact fix for each.

First, find the real error. A vague message like "connection failed" or a Java exception usually hides an HTTP status and a message from Google. Look for those in the tool's log or error details; they tell you which section below applies.

403 – "Missing or insufficient permissions" / PERMISSION_DENIED

The account you connect with isn't allowed to read the database.

Service account: in Google Cloud Console → IAM, give it the Cloud Datastore User role (read and write) or Cloud Datastore Viewer (read only).
Your own Google account: make sure it has a role on that project, and that you're signed in as the account you think you are.
Security Rules don't apply here. Server-side access with service accounts or Google credentials skips Firestore Security Rules; IAM roles are what count.

403 – "Cloud Firestore API has not been used in project … or it is disabled"

Enable the Cloud Firestore API (firestore.googleapis.com) for the project in Google Cloud Console → APIs & Services, wait a minute, and try again.

404 – database or project not found

Use the project ID (like my-app-3f2a1), not the project name or number. You can find it on the Firebase console's project settings page.
If you created a named database, set its name. Tools default to (default).
Check you actually created a Firestore database in that project. A new Firebase project has none until you click "Create database".

400 – "not available for Firestore in Datastore mode"

The database was created in Datastore mode, which doesn't support the Firestore API. You need a Datastore client for it, or a new database in Native mode.

"The query requires an index"

Queries that filter or sort on more than one field need a composite index. The error message includes a link that creates it for you in the console. Index builds can take a few minutes.

401 / invalid_grant / token errors

Service account key: download a fresh JSON key (IAM → Service accounts → Keys). Old keys may have been deleted or disabled. Keys that start with BEGIN RSA PRIVATE KEY are an old format; get a new JSON key.
Application Default Credentials: run gcloud auth application-default login again. Refresh tokens expire if unused for a while or if your password changes.
Clock: a computer clock that's several minutes off makes signed tokens look invalid. Turn on automatic time.

Can't reach the emulator

The Firestore emulator listens on 127.0.0.1:8080 by default. Check the port printed when you run firebase emulators:start.
Use 127.0.0.1 rather than localhost if you see connection refused; some systems resolve localhost to IPv6 first.
The emulator keeps data in memory. Restarting it empties the database unless you use --import / --export-on-exit.

Network, proxy and certificate errors

Company networks sometimes intercept HTTPS. If you see SSL or certificate errors, your IDE or Java runtime may need your company's root certificate, or a proxy configured. Try once from a different network to confirm.

A Firestore browser for JetBrains IDEs

We're building a Firestore browser for IntelliJ, WebStorm, PyCharm and Android Studio that shows the real Google error and the likely fix instead of a generic failure, and handles sub-collections at any depth. Want to know when it's out? Email us.