23 Errors and Troubleshooting

Working with the Oracle Backend for Firebase Database SDK and APIs involves performing CRUD operations, queries, transactions, and batch writes. While these operations are straightforward, developers may encounter errors due to invalid inputs, missing configurations, or permission issues. This chapter provides guidance on common errors, their causes, and troubleshooting steps to resolve them.

• Document Operations Errors
  
• Query Errors
  
• Transaction and Batch Write Errors
  
• Authentication and Security Rule Errors
  
• Console-Based Troubleshooting
  
• Key Notes
  

23.1 Document Operations Errors

Errors often occur during create, update, or delete operations when the document path, fields, or merge options are misconfigured.

Common Errors

• Invalid Document Path: Occurs when the specified path does not exist or is malformed.

  { "error": "Invalid document path" }
  

• Merge Conflicts Using merge: true incorrectly may cause conflicts if fields are not compatible.

  { "error": "Field type mismatch during merge" }
  

Troubleshooting

• Verify the document path matches the collection hierarchy.

• Use merge: false when replacing entire documents.

• Ensure field types are consistent across updates.

23.2 Query Errors

Queries may fail due to invalid filters, missing indexes, or unsupported operators.

Common Errors

• Invalid Operator: Using unsupported operators in queries.

  { "error": "Operator not supported: != on field" }
  

• Missing Index: Queries across collection groups require mandatory indexes.

  { "error": "Index required for collection group query" }
  

Troubleshooting

• Use only supported operators.

• Create indexes using the Console before running collection group queries.

• Check query syntax carefully in SDK calls.

23.3 Transaction and Batch Write Errors

Transactions and batch writes enforce atomicity. Errors occur when one or more operations fail.

Common Errors

• Partial Failure: One operation in a batch fails, causing rollback.

  { "error": "Batch write failed: document not found" }
  

• Permission Denied: Occurs when the user lacks privileges for one of the operations.

  { "error": "Permission denied for update operation" }
  

Troubleshooting

• Ensure all documents referenced in a batch exist.

• Verify that the database user has CREATE, UPDATE, and DELETE privileges.

• Use smaller batches to isolate problematic operations.

23.4 Authentication and Security Rule Errors

Database operations are tightly coupled with authentication and security rules. Errors may arise when rules block access.

Common Errors

• Unauthorized Access

  { "error": "Permission denied: user not authenticated" }
  

• Rule Violation

  { "error": "Security rule violation: update not allowed" }
  

Troubleshooting

• Ensure the client is authenticated via supported methods (Email/Password, Social Login, SAML/OIDC).

• Review security rules defined in the Console for collections and documents.

• Adjust rules to allow intended operations while maintaining security.

23.5 Console-Based Troubleshooting

The Oracle Backend for Firebase Console provides built‑in tools to help diagnose and resolve errors.

Console Steps

1. Log in to the Console.

2. Navigate to Projects → Database.

3. Use the Query Builder to run queries interactively and check for syntax or index issues.

4. Use the Security Rules Editor to validate rule expressions.

5. Apply changes and re‑run operations to confirm resolution.

23.6 Key Notes

• Always validate document paths and field types before performing operations.

• Create required indexes in advance for complex queries.

• Use the Console’s Error Logs for detailed diagnostics.

• Security rules are enforced at runtime - test them thoroughly using the Console.

• Batch writes and transactions are all‑or‑nothing; a single failure causes rollback.