Skip to content

Errors

There are two kinds of errors, and they reach you in two different ways:

When How
Firebase errors The server (or the SDK) says no: wrong password, permission denied, no network... The error argument of your callback
Python exceptions Your call cannot work at all: a bad path, a value Firebase cannot store, a call in the wrong order Raised at once, by the method you called; nothing is sent

Firebase errors

Every callback error is a FirebaseError (or a subclass): a dict you can also read with dots.

Key Type What
code int The error code (NSError.code). Its meaning depends on domain
description str A human-readable message (localizedDescription)
domain str Where it comes from, for example "FIRAuthErrorDomain"
underlying_error NSError or None The lower-level error that caused it, for debugging
def on_done(error):
    if error is not None:
        print(error.domain, error.code, error.description)
        # the same, as a dict:
        print(error["domain"], error["code"])

Per product

Most products add a name: the code's name in the product's error-code class, so you can compare names instead of numbers, and log something readable.

Product Error class Codes Domain Extra keys
Authentication AuthError AuthErrorCode AUTH_ERROR_DOMAIN name, email, updated_credential, resolver, cancelled, message
Cloud Functions FunctionsError FunctionsErrorCode FUNCTIONS_ERROR_DOMAIN name, details
Cloud Storage StorageError StorageErrorCode STORAGE_ERROR_DOMAIN name
Realtime Database DatabaseError DatabaseErrorCode DATABASE_ERROR_DOMAIN name
Cloud Messaging MessagingError MessagingErrorCode MESSAGING_ERROR_DOMAIN name
Remote Config FirebaseError RemoteConfigErrorCode REMOTE_CONFIG_ERROR_DOMAIN
App Check FirebaseError AppCheckErrorCode APP_CHECK_ERROR_DOMAIN
Firestore FirebaseError The gRPC status codes (Firestore errors) "FIRFirestoreErrorDomain"

name is "" when the error comes from another domain (for example a network error from the system, wrapped by Firebase).

from pyios_firebase.storage import StorageErrorCode


def on_downloaded(data, error):
    if error is None:
        show_image(data)
    elif error.code == StorageErrorCode.OBJECT_NOT_FOUND:
        show_placeholder()
    else:
        log(f"storage: {error.name or error.domain} {error.description}")

Errors that are not failures

Error Meaning
AuthError with cancelled=True The user closed a Google, Apple or web sign-in sheet
StorageErrorCode.CANCELLED You cancelled the upload or download
RemoteConfigFetchStatus.THROTTLED Fetched too often: the cached values are still used

Errors that carry what you need next

Error Use
AuthErrorCode.SECOND_FACTOR_REQUIRED error.resolver finishes the sign-in with a second factor (Multi-factor)
AuthErrorCode.ACCOUNT_EXISTS_WITH_DIFFERENT_CREDENTIAL error.email and error.updated_credential: sign in with the existing provider, then link
FunctionsError from an HttpsError error.details: what the function attached, as Python values

Python exceptions

The Firebase SDK raises an Objective-C exception for some mistakes. Python cannot catch those: the whole app aborts, with no traceback. pyios-firebase checks these cases before calling the SDK and raises a normal Python exception instead:

Product Raises For example
Firestore TypeError, ValueError A value Firestore cannot store (a set, a date without a time, a non-str key); an empty or too long in / not-in list; filters that cannot be combined; a limit of 0; an order after a cursor; limit_to_last without an order (the list)
Realtime Database ValueError, TypeError A key with . # $ [ ] /, nan, a datetime, ordering a query twice, a limit of 0, update paths inside each other
Cloud Functions TypeError Data JSON cannot carry: a datetime, a set, nan, inf
Analytics ValueError, TypeError A reserved or invalid event name, a bool parameter, more than 25 parameters
Performance ValueError, RuntimeError A name starting with _, a sixth attribute; a trace before core.configure(), starting a trace twice
Crashlytics RuntimeError A second unsent-report check in one launch (the SDK would answer "no report")
App Check RuntimeError Choosing a provider after core.configure()
Messaging ValueError An invalid topic name
In-App Messaging ValueError, RuntimeError An empty event name; in_app_messaging() before core.configure(); a custom display that finishes a message twice

Some of these the SDK would not abort on, but silently drop (an Analytics event, a Performance attribute): an exception tells you while you develop, instead of the data being missing in the console weeks later.

try:
    ref.child(user_input).set_value(data)
except ValueError as e:     # for example a "." in the user's input
    show(f"Invalid name: {e}")

Reporting errors to Crashlytics

Send unexpected Firebase errors and Python exceptions to Crashlytics, to see them as issues in the console:

from pyios_firebase.crashlytics import Crashlytics

crashlytics = Crashlytics.crashlytics()


def on_saved(error):
    if error is not None:
        crashlytics.record_error(error, {"screen": "checkout"})   # a FirebaseError works

See Crashlytics.