Postconditions: what we check

• verifyIdToken · token-expired

  error
  WhenID token has expired
  ThrowsFirebaseAuthError with code 'auth/id-token-expired'
  Required handlingCaller MUST catch and handle expired token errors. Return 401 Unauthorized to client and require re-authentication. DO NOT retry with same token - it's permanently expired.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• verifyIdToken · token-invalid

  error
  WhenID token is invalid (malformed, wrong project, revoked)
  ThrowsFirebaseAuthError with code 'auth/argument-error' or 'auth/id-token-revoked'
  Required handlingCaller MUST validate token format and handle invalid tokens. Check error.code to distinguish between format errors and revoked tokens. Return 401 Unauthorized to client.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[2]
• verifyIdToken · network-error

  error
  WhenNetwork request to Firebase Auth service failed
  ThrowsFirebaseAuthError or generic Error
  Required handlingCaller SHOULD implement retry with exponential backoff for transient failures. Check if Firebase Auth service is available.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[3]
• createUser · email-already-exists

  error
  WhenEmail address is already in use
  ThrowsFirebaseAuthError with code 'auth/email-already-exists'
  Required handlingCaller MUST check if error.code === 'auth/email-already-exists'. Return user-friendly error message. Consider suggesting password reset if user forgot they have an account. DO NOT retry with same email.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• createUser · invalid-email

  error
  WhenEmail format is invalid
  ThrowsFirebaseAuthError with code 'auth/invalid-email'
  Required handlingCaller SHOULD validate email format before calling createUser. Use email validation library to prevent this error.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• createUser · uid-already-exists

  error
  WhenProvided UID is already in use (when specifying custom UID)
  ThrowsFirebaseAuthError with code 'auth/uid-already-exists'
  Required handlingIf using custom UIDs, generate unique values. Catch this error and either generate new UID or handle collision.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• createUser · invalid-password

  error
  WhenPassword is too weak or doesn't meet requirements
  ThrowsFirebaseAuthError with code 'auth/invalid-password'
  Required handlingValidate password strength on client side. Firebase requires minimum 6 characters. Return helpful error to user about password requirements.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[4]
• getUser · user-not-found

  error
  WhenNo user record found for the given UID
  ThrowsFirebaseAuthError with code 'auth/user-not-found'
  Required handlingCaller MUST handle user-not-found errors. DO NOT assume user exists - always catch this error. Consider if this indicates deleted account or invalid UID.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• getUser · invalid-uid

  error
  WhenUID format is invalid
  ThrowsFirebaseAuthError with code 'auth/invalid-uid'
  Required handlingValidate UID format before calling getUser. Firebase UIDs are typically 28-character strings.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• updateUser · user-not-found

  error
  WhenNo user record found for the given UID
  ThrowsFirebaseAuthError with code 'auth/user-not-found'
  Required handlingCaller MUST handle user-not-found errors. Decide whether to create user or return error.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• updateUser · email-already-exists

  error
  WhenNew email address is already in use by another user
  ThrowsFirebaseAuthError with code 'auth/email-already-exists'
  Required handlingCheck if new email is available before updating. Return user-friendly error if email is taken.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• deleteUser · user-not-found

  error
  WhenNo user record found for the given UID
  ThrowsFirebaseAuthError with code 'auth/user-not-found'
  Required handlingCaller SHOULD handle user-not-found errors gracefully. Consider if idempotent delete is acceptable (user already deleted).
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• getUserByEmail · user-not-found

  error
  WhenNo user record with the given email
  ThrowsFirebaseAuthError with code 'auth/user-not-found'
  Required handlingCaller MUST handle user-not-found errors. This is common when checking if email is registered.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• setCustomUserClaims · user-not-found

  error
  WhenNo user record found
  ThrowsFirebaseAuthError with code 'auth/user-not-found'
  Required handlingVerify user exists before setting claims.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[1]
• setCustomUserClaims · invalid-claims

  error
  WhenClaims object exceeds 1000 bytes or uses reserved keys
  ThrowsFirebaseAuthError with code 'auth/invalid-claims'
  Required handlingValidate claims size and avoid reserved keys. Reserved keys: iss, sub, aud, exp, iat, auth_time, nonce, etc.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[5]
• get · permission-denied

  error
  WhenSecurity rules deny read access
  ThrowsError with code 'PERMISSION_DENIED' (gRPC code 7)
  Required handlingCaller MUST handle permission errors. Check Firestore security rules. Admin SDK bypasses rules by default - if seeing this, check service account permissions.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[6]
• get · not-found

  error
  WhenDocument does not exist
  ReturnsDocumentSnapshot with exists: false
  Required handlingCaller MUST check snapshot.exists before accessing data. Use snapshot.exists or check if snapshot.data() is undefined.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[7]
• get · deadline-exceeded

  error
  WhenOperation timed out
  ThrowsError with code 'DEADLINE_EXCEEDED' (gRPC code 4)
  Required handlingCaller SHOULD implement retry with exponential backoff. Check network connectivity and Firestore status. Consider if query is too complex (missing indexes).
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[6]
• add · permission-denied

  error
  WhenSecurity rules deny write access
  ThrowsError with code 'PERMISSION_DENIED' (gRPC code 7)
  Required handlingCheck Firestore security rules and service account permissions.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[6]
• add · resource-exhausted

  error
  WhenWrite quota exceeded or rate limit hit
  ThrowsError with code 'RESOURCE_EXHAUSTED' (gRPC code 8)
  Required handlingCaller MUST handle quota errors. Check if billing is enabled (free tier limits). Implement backoff and reduce write rate. Avoid writing to lexicographically close documents (hot spots).
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[8]
• set · aborted

  error
  WhenTransaction aborted due to contention
  ThrowsError with code 'ABORTED' (gRPC code 10)
  Required handlingCaller SHOULD retry with exponential backoff and jitter. Occurs when multiple transactions access same data. Consider redesigning to reduce contention.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[6]
• set · resource-exhausted

  error
  WhenWrite quota exceeded
  ThrowsError with code 'RESOURCE_EXHAUSTED'
  Required handlingImplement rate limiting and backoff. Check daily write quota and billing status.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[8]
• update · not-found

  error
  WhenDocument to update does not exist
  ThrowsError with code 'NOT_FOUND' (gRPC code 5)
  Required handlingCaller MUST handle not-found errors. Use set() with merge: true if you want to create-or-update. update() requires document to exist.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[9]
• update · aborted

  error
  WhenTransaction contention
  ThrowsError with code 'ABORTED'
  Required handlingRetry with exponential backoff.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[6]
• delete · permission-denied

  error
  WhenSecurity rules deny delete access
  ThrowsError with code 'PERMISSION_DENIED'
  Required handlingCheck security rules and permissions.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[6]
• send · invalid-recipient

  error
  WhenDevice token is invalid, expired, or unregistered
  ThrowsFirebaseMessagingError with code 'messaging/invalid-recipient'
  Required handlingCaller MUST remove invalid tokens from database. Check error code and error.code === 'messaging/invalid-recipient'. Tokens can expire if user uninstalls app or revokes permissions.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[10]
• send · invalid-argument

  error
  WhenMessage payload is malformed or exceeds size limits
  ThrowsFirebaseMessagingError with code 'messaging/invalid-argument'
  Required handlingValidate message structure before sending. Check payload size limits (4KB for data messages). Verify required fields are present.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[10]
• send · quota-exceeded

  error
  WhenFCM rate limit exceeded
  ThrowsFirebaseMessagingError with code 'messaging/quota-exceeded'
  Required handlingImplement exponential backoff retry. Reduce message send rate. Check if quota limit is reasonable for use case.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[10]
• sendMulticast · partial-failure

  error
  WhenSome tokens succeeded, some failed
  ReturnsBatchResponse with failureCount > 0
  Required handlingCaller MUST check response.failureCount and response.responses array. Each response contains success boolean and optional error. Remove invalid tokens from database based on specific error codes.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[11]
• sendMulticast · invalid-argument

  error
  WhenInvalid tokens or payload
  ThrowsFirebaseMessagingError
  Required handlingValidate all tokens and payload before sending.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[10]
• sendToTopic · invalid-topic

  error
  WhenTopic name is invalid or doesn't exist
  ThrowsFirebaseMessagingError with code 'messaging/invalid-argument'
  Required handlingValidate topic name format. Topic names must match /topics/[a-zA-Z0-9-_.~%]+
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[12]
• once · permission-denied

  error
  WhenDatabase rules deny read access
  ThrowsError with code 'PERMISSION_DENIED'
  Required handlingCheck Realtime Database rules. Admin SDK bypasses rules by default - if seeing this, check databaseAuthVariableOverride.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[13]
• once · network-error

  error
  WhenNetwork connection failed
  ThrowsError
  Required handlingImplement retry with exponential backoff for transient failures.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[3]
• set · permission-denied

  error
  WhenDatabase rules deny write access
  ThrowsError with code 'PERMISSION_DENIED'
  Required handlingCheck database rules and authentication.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[14]
• update · permission-denied

  error
  WhenDatabase rules deny write access
  ThrowsError with code 'PERMISSION_DENIED'
  Required handlingCheck database rules.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[14]
• remove · permission-denied

  error
  WhenDatabase rules deny delete access
  ThrowsError with code 'PERMISSION_DENIED'
  Required handlingCheck database rules.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[14]
• createSessionCookie · session-cookie-invalid-duration

  error
  WhenexpiresIn is not provided, not a number, or outside the allowed range (5 minutes to 2 weeks)
  ThrowsFirebaseAuthError with code 'auth/invalid-session-cookie-duration'
  Required handlingValidate expiresIn is a number between 300000ms (5 min) and 1209600000ms (2 weeks) before calling. Catch this error and return 400 Bad Request with a clear message. This error rejects synchronously — no network call is made.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[1]
• createSessionCookie · session-cookie-invalid-id-token

  error
  WhenID token is malformed, expired, or belongs to a different Firebase project
  ThrowsFirebaseAuthError with code 'auth/invalid-id-token'
  Required handlingCatch this error at the login endpoint and return 401 Unauthorized. The ID token must be recently issued (within 5 minutes). Require the front-end to obtain a fresh ID token and retry.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[1]
• createSessionCookie · session-cookie-network-error

  error
  WhenFirebase Auth service is unreachable
  ThrowsFirebaseAuthError or network Error
  Required handlingCatch network errors at the login endpoint and return 503 Service Unavailable. Implement exponential backoff retry for transient failures.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[1]
• verifySessionCookie · session-cookie-expired

  error
  WhenSession cookie's expiry time has passed
  ThrowsFirebaseAuthError with code 'auth/session-cookie-expired'
  Required handlingCatch in authentication middleware. Clear the session cookie and redirect to login. DO NOT retry — the cookie is permanently expired.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[1]
• verifySessionCookie · session-cookie-revoked

  error
  WhencheckRevoked=true and the user's session was revoked via revokeRefreshTokens()
  ThrowsFirebaseAuthError with code 'auth/session-cookie-revoked'
  Required handlingCatch in authentication middleware alongside cookie-expired. Clear the session cookie and redirect to login. Distinguish from expired for proper UX messaging.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[1]
• verifySessionCookie · session-cookie-invalid

  error
  WhenSession cookie is malformed, has invalid signature, or belongs to different Firebase project
  ThrowsFirebaseAuthError with code 'auth/argument-error' or similar
  Required handlingCatch in authentication middleware. Return 401 Unauthorized and clear the invalid cookie. Never swallow this error — tampered cookies must be rejected.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[1]
• verifySessionCookie · session-cookie-user-disabled

  error
  WhencheckRevoked=true and the user account has been disabled
  ThrowsFirebaseAuthError with code 'auth/user-disabled'
  Required handlingCatch separately from cookie-expired and cookie-revoked. Return a disabled-account response, not a generic 401. Requires network call to Firebase Auth.
  costmediumin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[1]
• createCustomToken · custom-token-invalid-uid

  error
  Whenuid is empty, not a string, or exceeds 128 characters
  ThrowsFirebaseAuthError with code 'auth/argument-error'
  Required handlingValidate uid is a non-empty string of 128 chars or fewer before calling. Catch and return 400 Bad Request. This rejects synchronously before signing.
  costmediumin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[15]
• createCustomToken · custom-token-invalid-claims

  error
  WhendeveloperClaims contains reserved JWT keys (iss, sub, aud, exp, iat, firebase, etc.)
  ThrowsFirebaseAuthError with code 'auth/argument-error'
  Required handlingAvoid reserved JWT claim keys in developerClaims. Validate claims object does not contain reserved names before calling. Catch and return 400.
  costmediumin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[15]
• createCustomToken · custom-token-signing-error

  error
  WhenService account private key is invalid, revoked, or corrupt
  ThrowsFirebaseAuthError with code 'auth/invalid-credential'
  Required handlingCatch and alert on this error — it indicates service account misconfiguration. Return 500 Internal Server Error. Do not retry. Requires manual key rotation fix.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[15]
• revokeRefreshTokens · revoke-tokens-user-not-found

  error
  WhenUID does not correspond to an existing Firebase user
  ThrowsFirebaseAuthError with code 'auth/user-not-found'
  Required handlingCatch and treat as success — user is already gone so revocation is moot. Log the discrepancy but do not crash the security incident handler.
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[1]
• revokeRefreshTokens · revoke-tokens-network-error

  error
  WhenFirebase Auth service is unreachable during revocation
  ThrowsFirebaseAuthError or network Error
  Required handlingMUST catch and retry on network failure. Failed revocation during a security incident leaves compromised sessions active. Implement exponential backoff. Alert if retries are exhausted.
  costhighin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[1]
• generatePasswordResetLink · password-reset-user-not-found

  error
  WhenNo user exists with the specified email address
  ThrowsFirebaseAuthError with code 'auth/email-not-found' or 'auth/user-not-found'
  Required handlingCatch and return success regardless to prevent email enumeration attacks. Do not reveal whether the email is registered. Log the error internally.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• generatePasswordResetLink · password-reset-invalid-email

  error
  WhenEmail format is invalid
  ThrowsFirebaseAuthError with code 'auth/invalid-email'
  Required handlingValidate email format with a regex or Zod schema before calling. Catch and return 400 Bad Request with a user-friendly message.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• runTransaction · transaction-aborted-max-retries

  error
  WhenTransaction contention persists across all 5 automatic retry attempts
  ThrowsError with gRPC code ABORTED (code 10) — message: 'Too much contention on these datastore entities. Please try again.'
  Required handlingCatch the final rejection after retries are exhausted and return a 409 Conflict or retry the full operation at the application level with backoff. Do not swallow this error — silent swallowing causes lost writes that appear as stale data.
  costhighin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[6]
• runTransaction · transaction-deadline-exceeded

  error
  WhenTransaction execution exceeds Firestore's 60-second server deadline
  ThrowsError with gRPC code DEADLINE_EXCEEDED (code 4)
  Required handlingCatch and treat as a non-retryable failure — the transaction was rolled back. For background jobs, return a failure result. For API routes, return 503. Break large transactions into smaller units to avoid hitting the deadline.
  costhighin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[6]
• runTransaction · transaction-failed-offline

  error
  WhenFirestore service is unreachable or the network connection is unavailable
  ThrowsError with gRPC code UNAVAILABLE (code 14)
  Required handlingCatch and implement external retry with exponential backoff. The Admin SDK does NOT queue offline — it fails immediately. Background jobs MUST retry externally when UNAVAILABLE errors occur during network partitions.
  costhighin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[6]
• runTransaction · transaction-function-side-effects

  warning
  WhenThe transaction update function contains side effects that execute on every retry attempt
  ThrowsNo throw — side effects execute silently N times (up to 5)
  Required handlingKeep the updateFunction free of observable side effects beyond Firestore writes. Move external API calls, payments, and email sends to AFTER the transaction resolves.
  costhighin prodsilent failureusers seelost transactionvisibilitysilent
  Sources[16]
• commit · batch-resource-exhausted

  error
  WhenWrite quota is exceeded or batch causes a hot-spot on a document
  ThrowsError with gRPC code RESOURCE_EXHAUSTED (code 8)
  Required handlingCatch and implement exponential backoff retry. Batch commits that hit RESOURCE_EXHAUSTED have NOT been applied — retry the full batch. Add jitter to backoff to prevent thundering herd in serverless deployments.
  costhighin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[6]
• commit · batch-aborted

  error
  WhenBatch write fails due to document contention
  ThrowsError with gRPC code ABORTED (code 10)
  Required handlingCatch ABORTED and retry the full batch from scratch. WriteBatch does NOT automatically retry unlike runTransaction(). No writes are applied on ABORTED — the batch is atomic and all-or-nothing.
  costhighin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[6]
• commit · batch-too-many-operations

  error
  WhenBatch contains more than 500 write operations
  ThrowsError with gRPC INVALID_ARGUMENT — Firestore's hard 500-operation limit per batch
  Required handlingSplit large datasets into chunks of 500 or fewer before committing. Validate batch size before calling commit(). The SDK throws before sending to the server — no partial writes occur.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[16]
• sendEach · send-each-partial-failure

  error
  WhenOne or more messages fail to send while others succeed (partial failure)
  ThrowsPromise resolves with BatchResponse where failureCount > 0; does NOT reject on partial failure
  Required handlingAfter every sendEach() call, check response.failureCount. If > 0, iterate response.responses to find per-message errors. Remove tokens with 'messaging/registration-token-not-registered' from the database. failureCount === messages.length means total failure with no deliveries.
  costmediumin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[11]
• sendEach · send-each-rate-exceeded

  error
  WhenGlobal FCM send rate limit is exceeded during batch send
  ThrowsFirebaseMessagingError with code 'messaging/message-rate-exceeded'
  Required handlingCatch and implement exponential backoff before retrying. This is a global rate limit (not per-device). Reduce send frequency or fan out over time. Distinguish from per-device 'messaging/device-message-rate-exceeded' errors that appear in per-message response.responses[i].error.
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[10]
• sendEach · send-each-invalid-argument

  error
  WhenMessage payloads are malformed, tokens are empty strings, or required fields are missing
  ThrowsFirebaseMessagingError with code 'messaging/invalid-argument'
  Required handlingValidate all message objects before calling sendEach(). Ensure tokens are non-empty strings. Catch and return 400 Bad Request. Input validation before the call prevents the entire batch from being rejected.
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[10]
• subscribeToTopic · subscribe-partial-failure

  error
  WhenOne or more tokens fail to subscribe while others succeed
  ThrowsPromise resolves with MessagingTopicManagementResponse where errors array is non-empty; does NOT reject
  Required handlingAfter every subscribeToTopic() call, check response.errors array. Remove tokens with 'messaging/registration-token-not-registered' from the database. Partial success means some tokens were subscribed; do not assume all succeeded when Promise resolves.
  costlowin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[17]
• subscribeToTopic · subscribe-invalid-topic

  error
  WhenTopic name is invalid — does not match /topics/[a-zA-Z0-9-_.~%]+ pattern
  ThrowsFirebaseMessagingError with code 'messaging/invalid-argument'
  Required handlingValidate topic names before calling. Topic names must match [a-zA-Z0-9-_.~%]+ (the /topics/ prefix is added automatically if omitted). Catch and return 400 Bad Request for invalid topic name inputs.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[17]
• importUsers · import-users-batch-too-large

  error
  Whenusers array contains more than 1000 records
  ThrowsFirebaseAuthError with code 'auth/maximum-user-count-exceeded'
  Required handlingSplit user arrays into chunks of 1000 before calling importUsers(). The SDK throws synchronously before any network call. Validate batch size before calling to avoid this failure mid-migration.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[18]
• importUsers · import-users-partial-failure

  error
  WhenOne or more individual user records fail validation or import while others succeed
  ThrowsPromise RESOLVES with UserImportResult where failureCount > 0; does NOT reject on per-user failure
  Required handlingAfter every importUsers() call, check result.failureCount. If > 0, inspect result.errors array — each entry contains index (original array position) and error (the failure reason). DO NOT assume all users were imported when the Promise resolves. Per-user failures include invalid email, duplicate UID, invalid password hash, and provider data conflicts. Log per-user errors for remediation.
  costhighin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[19]
• importUsers · import-users-tenant-mismatch

  error
  WhenUser records contain tenantId fields that don't match the TenantAwareAuth tenant context
  ThrowsFirebaseAuthError with code 'auth/mismatching-tenant-id'
  Required handlingWhen using multi-tenancy: ensure all user records in the batch have tenantId matching the TenantAwareAuth instance. Catch this error and reject the entire import batch — this is a configuration error.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[18]
• generateSignInWithEmailLink · sign-in-link-missing-action-code-settings

  error
  WhenactionCodeSettings parameter is missing, null, or undefined
  ThrowsFirebaseAuthError with code 'auth/argument-error' — 'actionCodeSettings is required'
  Required handlingAlways pass actionCodeSettings with at least url (the deep link the user is redirected to after clicking). This error is thrown synchronously — no network call occurs. Catch and return 400 Bad Request.
  costlowin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[18]
• generateSignInWithEmailLink · sign-in-link-user-not-found

  error
  WhenNo Firebase user exists with the given email address
  ThrowsFirebaseAuthError with code 'auth/email-not-found' or 'auth/user-not-found'
  Required handlingFor sign-in links, user-not-found may indicate the email is not registered. Catch and return success regardless to prevent email enumeration attacks. Do not reveal whether the email is registered.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• generateSignInWithEmailLink · sign-in-link-network-error

  error
  WhenFirebase Auth service is unreachable
  ThrowsFirebaseAuthError or network Error
  Required handlingCatch and retry with exponential backoff for transient failures. Return 503 to the caller if retries are exhausted.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• generateVerifyAndChangeEmailLink · verify-change-email-missing-new-email

  error
  WhennewEmail parameter is undefined, null, or missing
  ThrowsFirebaseAuthError with code 'auth/argument-error' — 'newEmail is required'
  Required handlingAlways pass newEmail as the second argument. This error is thrown synchronously — no network call occurs. Validate both email and newEmail before calling. Catch and return 400 Bad Request.
  costlowin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[18]
• generateVerifyAndChangeEmailLink · verify-change-email-invalid-email

  error
  WhenCurrent email or newEmail is not a valid email format
  ThrowsFirebaseAuthError with code 'auth/invalid-email'
  Required handlingValidate both email addresses with a regex or Zod schema before calling. Catch and return 400 Bad Request with a user-friendly message.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• generateVerifyAndChangeEmailLink · verify-change-email-user-not-found

  error
  WhenNo user exists with the given current email address
  ThrowsFirebaseAuthError with code 'auth/email-not-found' or 'auth/user-not-found'
  Required handlingCatch and handle gracefully. Avoid revealing whether email is registered in publicly accessible endpoints (email enumeration prevention).
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• getTemplate · remote-config-get-permission-denied

  error
  WhenService account lacks Remote Config Viewer or Editor role
  ThrowsFirebaseRemoteConfigError with code 'remote-config/permission-denied'
  Required handlingCatch and alert — this is a service account misconfiguration that will prevent all Remote Config reads. Return 500 to the caller. Grant the Firebase Remote Config Admin role to the service account in IAM. Do not retry — this error is not transient.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[20]
• getTemplate · remote-config-get-quota-exceeded

  warning
  WhenRemote Config REST API quota is exceeded (default: 2000 requests/day for GET)
  ThrowsFirebaseRemoteConfigError with code 'remote-config/resource-exhausted'
  Required handlingCache the Remote Config template locally rather than fetching it on every request. Implement a TTL-based cache (Firebase recommends 15 minutes for most use cases). Catch this error and serve the last cached template. Do not fetch on every user request — this rapidly exhausts quota.
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[21]
• getTemplate · remote-config-get-network-error

  error
  WhenFirebase Remote Config service is unreachable or network fails
  ThrowsFirebaseRemoteConfigError with code 'remote-config/unknown-error' or network Error
  Required handlingCatch and serve last cached template if available. Implement exponential backoff retry for transient failures. Do not crash the application when Remote Config is temporarily unavailable — serve defaults instead.
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[20]
• publishTemplate · remote-config-publish-etag-mismatch

  error
  WhenTemplate ETag does not match the current server ETag — another process published the template after getTemplate() was called
  ThrowsFirebaseRemoteConfigError with code 'remote-config/aborted'
  Required handlingCatch 'remote-config/aborted' and retry: call getTemplate() to get the latest template, reapply your changes to it, then call publishTemplate() again. This prevents overwriting concurrent changes. Using force:true bypasses the ETag but risks losing changes made by other processes.
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[20]
• publishTemplate · remote-config-publish-invalid-template

  error
  WhenTemplate has missing ETag, invalid conditions, or malformed parameter values
  ThrowsFirebaseRemoteConfigError with code 'remote-config/invalid-argument'
  Required handlingCall validateTemplate() before publishTemplate() to catch structural errors without committing them. Catch 'invalid-argument' and log the error details — these indicate template schema violations.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[20]
• publishTemplate · remote-config-publish-quota-exceeded

  error
  WhenRemote Config write quota exceeded (default: 1 publish per second per project)
  ThrowsFirebaseRemoteConfigError with code 'remote-config/resource-exhausted'
  Required handlingImplement rate limiting before publishing — only one publish per second is allowed. Catch this error and retry after a 1-second delay. Do not use publishTemplate() in hot code paths — it is an admin operation.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[21]
• validateTemplate · remote-config-validate-invalid-argument

  error
  WhenTemplate has missing ETag, malformed conditions, invalid parameter names, or circular references
  ThrowsFirebaseRemoteConfigError with code 'remote-config/invalid-argument'
  Required handlingCatch and inspect the error message — the server returns specific details about what is invalid (e.g., invalid condition expression, reserved parameter name). Fix the template structure before retrying. This is the expected failure mode — validateTemplate() is specifically designed to surface these errors before they affect production.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[20]
• validateTemplate · remote-config-validate-permission-denied

  error
  WhenService account lacks Remote Config Editor or Admin role
  ThrowsFirebaseRemoteConfigError with code 'remote-config/permission-denied'
  Required handlingCatch and alert on this error — it indicates service account misconfiguration. The service account requires Firebase Remote Config Admin role, not just Viewer. Return 500 Internal Server Error. Do not retry.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[20]
• createProviderConfig · create-provider-config-invalid-provider-id

  error
  WhenproviderId does not start with 'saml.' or 'oidc.' prefix, or is missing from the config object entirely
  ThrowsFirebaseAuthError with code 'auth/invalid-provider-id'
  Required handlingValidate providerId format before calling createProviderConfig. OIDC provider IDs must start with 'oidc.' and SAML with 'saml.'. This is a synchronous validation error — no retry is useful. Return 400 Bad Request with clear description of required format.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[22]
• createProviderConfig · create-provider-config-quota-exceeded

  error
  WhenProject has reached the maximum number of SAML or OIDC provider configurations
  ThrowsFirebaseAuthError with code 'auth/quota-exceeded'
  Required handlingCatch and surface this as a billing/plan limit error. The project has hit the GCIP provider config limit. Do not retry — the error persists until existing configs are deleted. Return 429 or 503 with explanation to the calling service.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[23]
• createProviderConfig · create-provider-config-insufficient-permission

  error
  WhenService account lacks Identity Platform Admin or required IAM role
  ThrowsFirebaseAuthError with code 'auth/insufficient-permission'
  Required handlingCatch and alert — this is a service account misconfiguration. The service account requires the 'Firebase Authentication Admin' or 'identitytoolkit.admin' IAM role. Do not retry. Return 500 Internal Server Error and alert on-call.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[23]
• updateProviderConfig · update-provider-config-not-found

  error
  WhenNo provider configuration exists for the given providerId
  ThrowsFirebaseAuthError with code 'auth/configuration-not-found'
  Required handlingCatch and handle this as a 404. The provider config was deleted or never created. Verify the providerId is correct and the config exists before updating. Do not retry with same ID — the error is permanent until the config is created.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[24]
• updateProviderConfig · update-provider-config-invalid-config

  error
  WhenupdatedConfig is null, not an object, or contains invalid field values
  ThrowsFirebaseAuthError with code 'auth/invalid-config'
  Required handlingValidate configuration object before calling updateProviderConfig. OIDC requires clientId, issuer, and clientSecret for code flow. SAML requires idpEntityId, ssoURL, and x509Certificates. Catch and return 400 Bad Request with specific field validation errors.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[24]
• deleteProviderConfig · delete-provider-config-not-found

  error
  WhenNo provider configuration exists for the given providerId
  ThrowsFirebaseAuthError with code 'auth/configuration-not-found'
  Required handlingTreat as idempotent in most cases — the config is already gone. If this is unexpected (e.g., double-delete race), log and handle gracefully. Do NOT surface this as an error to the end user in an admin UI — the outcome (config is gone) is the desired state.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[24]
• getProviderConfig · get-provider-config-not-found

  error
  WhenNo provider configuration exists for the given providerId
  ThrowsFirebaseAuthError with code 'auth/configuration-not-found'
  Required handlingCatch and handle as 404. This is a normal condition when checking if a provider is configured. Do not assume provider exists — always catch this error in admin management workflows.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[24]
• createTenant · create-tenant-invalid-tenant-id

  error
  WhentenantId in options is an empty string or invalid format
  ThrowsFirebaseAuthError with code 'auth/invalid-tenant-id'
  Required handlingValidate tenantId before calling createTenant. Tenant IDs must be non-empty strings. If using auto-generated IDs, omit the tenantId field and Firebase will generate one. Catch and return 400 Bad Request.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[22]
• createTenant · create-tenant-missing-display-name

  error
  WhendisplayName is required but missing from tenant options
  ThrowsFirebaseAuthError with code 'auth/missing-display-name'
  Required handlingAlways include a displayName when creating tenants. The displayName is required by GCIP for tenant creation and is used in the Firebase Console and audit logs. Catch and return 400 with field validation details.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[23]
• createTenant · create-tenant-quota-exceeded

  error
  WhenProject has reached the maximum number of tenants for the GCIP plan
  ThrowsFirebaseAuthError with code 'auth/quota-exceeded'
  Required handlingCatch and surface as a billing/capacity limit. Contact Google Cloud support to increase tenant quota. Do not retry — the error is persistent until quota is increased or existing tenants are deleted. Alert operations team immediately.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[23]
• updateTenant · update-tenant-not-found

  error
  WhenNo tenant exists for the provided tenantId
  ThrowsFirebaseAuthError with code 'auth/tenant-not-found'
  Required handlingCatch and handle as 404. Verify the tenantId is correct. This can occur if a tenant was deleted between reads. Do not retry — the tenant must be recreated if missing. Return 404 to calling service.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[22]
• updateTenant · update-tenant-invalid-tenant-type

  error
  WhenAttempting to change the tenant type (full_service vs lightweight) after creation
  ThrowsFirebaseAuthError with code 'auth/invalid-tenant-type'
  Required handlingTenant type cannot be changed after creation. Remove the tenantType field from update requests if the type is already set. This is a permanent constraint — the only fix is to delete and recreate the tenant.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[23]
• deleteTenant · delete-tenant-not-found

  warning
  WhenNo tenant exists for the provided tenantId
  ThrowsFirebaseAuthError with code 'auth/tenant-not-found'
  Required handlingTreat as idempotent — the tenant is already gone. In offboarding workflows, this is generally safe to ignore. Log the occurrence for audit trails (the tenant may have been deleted by a concurrent request or external process).
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[22]
• getTenant · get-tenant-not-found

  error
  WhenNo tenant exists for the provided tenantId
  ThrowsFirebaseAuthError with code 'auth/tenant-not-found'
  Required handlingCatch and handle as 404. Always check tenant existence before performing tenant-scoped operations. If tenantId comes from user input or external systems, validate it with getTenant before calling authForTenant(). Return 404 to calling service.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[23]
• setRules · set-rules-invalid-argument

  error
  Whensource is null, undefined, empty string, or not a string/Buffer/object
  ThrowsFirebaseDatabaseError with code 'database/invalid-argument'
  Required handlingValidate rules source before calling setRules. The source must be a non-empty string (rules JSON), a Buffer containing rules, or a parsed object. Never pass null or empty string. This is a synchronous validation — no network call is made.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[25]
• setRules · set-rules-permission-denied

  error
  WhenService account lacks firebaserules.rulesets.create IAM permission or Firebase Admin role
  ThrowsFirebaseDatabaseError with HTTP 403 / permission-denied
  Required handlingCatch and alert — this is a service account misconfiguration in the deployment environment. The service account requires the Firebase Admin SDK Service Agent role or firebaserules.rulesets.create permission. Do not retry. Alert the deployment pipeline — rules were NOT updated.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[25]
• getDownloadURL · get-download-url-no-token

  error
  WhenFile exists in Cloud Storage but has no Firebase download token. Files uploaded directly via Google Cloud Storage APIs (not Firebase SDK) do not have download tokens by default.
  ThrowsFirebaseError with code 'storage/no-download-token'
  Required handlingCatch and handle: create a download token by updating the file's metadata via the Firebase Console or by calling file.setMetadata() to add a firebaseStorageDownloadTokens metadata entry. Files uploaded via Firebase Client SDK automatically have tokens. Files uploaded via @google-cloud/storage SDK do NOT have tokens unless explicitly added. This is a common pitfall in hybrid upload architectures.
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[26]
• getDownloadURL · get-download-url-file-not-found

  error
  WhenFile does not exist in the Cloud Storage bucket
  ThrowsError with HTTP 404 from Google Cloud Storage API
  Required handlingCatch HTTP 404 errors — this occurs when the file path is incorrect, the file was deleted, or the bucket name is wrong. Always verify file existence before generating download URLs in critical workflows. Return 404 to the calling client.
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[26]
• executeGraphql · data-connect-invalid-argument

  error
  WhenGraphQL query is empty, not a string, or options object is malformed
  ThrowsFirebaseDataConnectError with code 'data-connect/invalid-argument'
  Required handlingCatch this error to surface developer mistakes during query construction. The most common cause is interpolating an undefined variable into the query template (producing an empty string) or passing a non-object as options. Log the query for debugging and return a 400-class error to upstream callers — do NOT retry.
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[27][28]
• executeGraphql · data-connect-permission-denied

  error
  WhenService account lacks Data Connect access on the target service/connector, or the impersonated auth principal is denied by GraphQL auth directives.
  ThrowsFirebaseDataConnectError with code 'data-connect/permission-denied' or 'data-connect/unauthenticated'
  Required handlingCatch and alert — this indicates either service-account IAM misconfiguration (Data Connect Editor / Admin role missing) or that the impersonated end-user lacks permission for the queried operation. Do NOT retry with the same credentials. For impersonation paths, propagate as 403 to the client.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[27][29]
• executeGraphql · data-connect-network-error

  error
  WhenNetwork request to the Data Connect REST endpoint failed (DNS failure, connection reset, gateway timeout, or 5xx response from Google Cloud).
  ThrowsFirebaseDataConnectError with code 'data-connect/internal-error' or 'data-connect/unknown-error'
  Required handlingCatch and implement retry with exponential backoff for transient failures. Distinguish retriable (5xx, ECONNRESET) from non-retriable (4xx) errors by inspecting the wrapped error code. Surface persistent failures as 503 to the upstream caller so SLO alerts fire. Long-running migration scripts MUST checkpoint progress so a transient failure does not require a full restart.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[27]
• executeGraphql · data-connect-query-error

  error
  WhenServer rejected the GraphQL operation — typical causes are referenced table/column does not exist, type mismatch, or Postgres constraint violation (unique key, foreign key, not-null) on a mutation.
  ThrowsFirebaseDataConnectError with code 'data-connect/query-error'
  Required handlingCatch and inspect the error message — the server returns the specific GraphQL error detail. Constraint violations are user-recoverable (e.g. surface 'email already exists' to the UI); schema mismatches indicate a developer bug and MUST be alerted. Do NOT retry — re-running the same query produces the same failure.
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[28][29]
• verifyToken · phone-verify-token-invalid

  error
  WhenToken argument is not a string, is malformed (cannot be JWT-decoded), has the wrong issuer, wrong audience (Firebase project ID mismatch), missing/invalid signature, or no matching JWKS key id.
  ThrowsFirebasePhoneNumberVerificationError with code 'phone-number-verification/invalid-token' or '/invalid-argument'
  Required handlingCatch and return 401 Unauthorized to the caller. Treat this as a hostile input — the most common production source is a forged or tampered token, NOT a legitimate user error. Log the verification failure for audit but do not echo the token contents to the client. DO NOT retry — a token that fails signature/issuer verification will never succeed.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[30][31]
• verifyToken · phone-verify-token-expired

  error
  WhenPhone-verification JWT exp claim is in the past
  ThrowsFirebasePhoneNumberVerificationError with code 'phone-number-verification/expired-token'
  Required handlingCatch and return 401 Unauthorized. Distinguish expired tokens from invalid ones via error.code — expired tokens are a normal lifecycle event (the user's verification window closed) and the client should be instructed to restart the phone-verification flow, not retry the same token. DO NOT extend the trust window by ignoring the error.
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[30]
• verifyToken · phone-verify-project-or-network-error

  error
  WhenApp was initialized without a project ID (no service-account credential and no GOOGLE_CLOUD_PROJECT env var), or the JWKS endpoint network fetch failed transiently.
  ThrowsFirebasePhoneNumberVerificationError with code 'phone-number-verification/invalid-argument'
  Required handlingCatch and alert — for the project-id case this is a deployment-time misconfiguration that requires fixing the service-account credential or GOOGLE_CLOUD_PROJECT env var. For the JWKS network case, return 503 to the caller so SLO alerts fire and clients can retry. DO NOT silently fall back to trusting the unverified token.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[30]
• TaskQueue.enqueue · task-queue-enqueue-already-exists

  error
  WhenTaskOptions.id is set to an explicit value and a task with that ID already exists in the queue, or was deleted/executed within the last ~1 hour (deduplication window).
  ThrowsFirebaseFunctionsError with code 'functions/task-already-exists'
  Required handlingCaller MUST either catch and treat this as idempotent success (task is already queued — no action needed), or use a different ID. Do NOT retry blindly — the same ID will fail again until the deduplication window expires. If at-least-once semantics are acceptable, catch and continue. If exactly-once is required, check error.code before deciding whether to surface the error upstream.
  costmediumin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[32][33][34]
• TaskQueue.enqueue · task-queue-enqueue-permission-denied

  error
  WhenThe service account lacks the cloudtasks.tasks.create IAM permission, or the Cloud Tasks API is not enabled for the project.
  ThrowsFirebaseFunctionsError with code 'functions/permission-denied'
  Required handlingThis is a deployment-time configuration error — fix the service account IAM binding before retrying. Grant roles/cloudtasks.enqueuer or a custom role with cloudtasks.tasks.create. Do NOT retry in code — the permission check is server-side and will fail repeatedly.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[32][34]
• TaskQueue.enqueue · task-queue-enqueue-not-found

  error
  WhenThe Cloud Functions task-queue function referenced by functionName is not deployed or does not exist in the specified project/location.
  ThrowsFirebaseFunctionsError with code 'functions/not-found'
  Required handlingVerify the function name is correct and deployed. In multi-environment setups, check that the function is deployed in the environment matching the Firebase app's project. Fail fast with an alert — tasks cannot be enqueued for a function that doesn't exist.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[32][34]
• TaskQueue.delete · task-queue-delete-not-found

  error
  WhenThe task with the given ID does not exist in the queue — either it was already executed, already deleted, never enqueued, or the deduplication window has passed.
  ThrowsFirebaseFunctionsError with code 'functions/not-found'
  Required handlingCaller SHOULD handle not-found as an idempotent no-op in most cancellation scenarios — the task may have already executed before the cancellation request arrived. If strict delivery-guarantees are required (task must not run), treat not-found as an error requiring investigation.
  costlowin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[32][34]
• Channel.publish · eventarc-publish-invalid-argument

  error
  WhenThe CloudEvent payload is missing required fields (id, source, type, specversion), contains an invalid field type, or the channel resource name is malformed.
  ThrowsFirebaseEventarcError with code 'eventarc/invalid-argument'
  Required handlingValidate CloudEvent structure before publishing. Required fields: id (unique per event), source (URI), type (reverse-DNS string), specversion ('1.0'). A missing or malformed field throws immediately before the network call is made. Fix the event construction — retrying the same payload produces the same failure.
  costmediumin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[35][36][37]
• Channel.publish · eventarc-publish-permission-denied

  error
  WhenThe publisher service account lacks eventarc.events.create permission on the Eventarc channel, or the Eventarc API is not enabled for the project.
  ThrowsFirebaseEventarcError with code 'eventarc/unknown-error' (wraps 403 HTTP response)
  Required handlingGrant the service account roles/eventarc.eventPublisher or the specific eventarc.events.create permission. This is a deployment-time configuration error — retrying in code will not help. Alert on-call immediately as all event publications from this service are silently failing.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[38][39]
• RemoteConfig.rollback · remote-config-rollback-version-not-found

  error
  WhenThe specified version number does not exist — it was never published, was deleted due to staleness (older than 90 days and no longer active), or exceeds the 300-version retention window.
  ThrowsFirebaseRemoteConfigError with code 'remote-config/not-found'
  Required handlingCatch and alert. During an incident rollback, a not-found error means the target version is unavailable — fall back to the next-older known-good version. Use listVersions() to inspect the available version window before calling rollback(). Do NOT retry with the same version number.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[40][41]
• RemoteConfig.rollback · remote-config-rollback-invalid-version

  error
  WhenThe specified version number is invalid — it is greater than or equal to the current version, or is not a positive integer.
  ThrowsFirebaseRemoteConfigError with code 'remote-config/failed-precondition' or 'remote-config/invalid-argument'
  Required handlingValidate that the target version number is less than the current template version (available from template.version.versionNumber after getTemplate()). Rollback to the same or newer version is logically invalid.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[40][41]
• RemoteConfig.getServerTemplate · remote-config-server-template-auth-error

  error
  WhenThe service account lacks Firebase Remote Config Viewer or Admin permission, or the Remote Config REST API is not enabled for the project. Also fires if the credentials have expired (UNAUTHENTICATED).
  ThrowsFirebaseRemoteConfigError with code 'remote-config/permission-denied' or 'remote-config/unauthenticated'
  Required handlingGrant roles/firebaseremoteconfig.viewer to the service account. If the credential has expired, re-initialize the Admin SDK. This error blocks all server-side personalization — surface as a startup error rather than letting it manifest as a runtime NullPointerException when using the template object.
  costhighin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[42][41]
• MachineLearning.createModel · ml-create-model-already-exists

  error
  WhenA model with the same display name already exists in the project.
  ThrowsFirebaseMachineLearningError with code 'machine-learning/already-exists'
  Required handlingCatch and either update the existing model via updateModel() or use a unique display name. In idempotent create-or-update flows, catch this error, retrieve the existing model, and call updateModel() with the new model file URI.
  costlowin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[43][44]
• MachineLearning.createModel · ml-create-model-invalid-argument

  error
  WhenThe model options are invalid — display name is empty, gcsTfliteUri is malformed, or the referenced GCS file is not a valid TFLite model.
  ThrowsFirebaseMachineLearningError with code 'machine-learning/invalid-argument'
  Required handlingValidate model options before calling createModel(). Verify the GCS URI format (gs://bucket/path/to/model.tflite) and that the file exists and is a valid TFLite model. A malformed URI causes an immediate error before any upload attempt.
  costlowin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[43][44]
• MachineLearning.publishModel · ml-publish-model-not-found

  error
  WhenThe model with the given modelId does not exist in the project — it was never created, or was deleted before publish was called.
  ThrowsFirebaseMachineLearningError with code 'machine-learning/not-found'
  Required handlingCatch and fail the deployment pipeline with a clear error. In CI/CD model-deployment flows, treat this as a fatal error requiring manual intervention — a missing model cannot be auto-recovered by retrying.
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[43][44]
• MachineLearning.publishModel · ml-publish-model-failed-precondition

  error
  WhenThe model is in a locked state due to a concurrent operation (e.g. the model file is still being processed or validated by Firebase ML).
  ThrowsFirebaseMachineLearningError with code 'machine-learning/failed-precondition'
  Required handlingCatch and poll for the model to reach a non-locked state using getModel() before retrying publishModel(). Implement exponential backoff with a reasonable timeout (e.g. 60 seconds) — model processing is typically fast but can be slow for large models.
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[43][44]
• MachineLearning.deleteModel · ml-delete-model-not-found

  error
  WhenThe model with the given modelId does not exist — it was already deleted or the ID was never valid.
  ThrowsFirebaseMachineLearningError with code 'machine-learning/not-found'
  Required handlingCaller SHOULD treat not-found as an idempotent success in cleanup workflows (the goal was to remove the model — it's already gone). If strict deletion confirmation is required, propagate the error as a deletion-failed alert.
  costlowin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[43][44]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.

// Authentication (2-level chains)
admin.auth().verifyIdToken(token)
admin.auth().createUser(properties)

// Firestore (3-4 level chains)
admin.firestore().collection('users').doc('id').get()
admin.firestore().collection('users').add(data)

// Messaging (2-level chains)
admin.messaging().send(message)

// Database (3-level chains)
admin.database().ref('path').once('value')