Data Browser App

Troubleshooting

Troubleshooting

This guide covers common issues you may encounter when using the Data Browser App and how to resolve them.

Common Issues

Issue: Collections Not Loading

Symptoms:

  • Sidebar shows empty or loading state indefinitely
  • "No collections found" message appears
  • Error message in the sidebar area

Cause: Usually caused by database initialization issues or connection problems.

Solution:

  1. Refresh the page to reinitialize the database connection
  2. Check browser console for RxDB errors
  3. Verify you're logged into the correct organization/workspace
  4. Ensure the RxDB database has been properly initialized
  5. If using REST mode, verify the server is running and accessible

Issue: Data Table Shows Empty

Symptoms:

  • Collection selected but no data appears
  • Empty state message shown
  • Pagination shows 0 results

Cause: May be caused by filters, no data in collection, or query errors.

Solution:

  1. Clear all filters using the "Clear Filters" button
  2. Verify the collection actually contains documents
  3. Check if filters are too restrictive
  4. In REST mode, verify server connection is working
  5. Try switching to Local mode to compare results

Issue: Cannot Edit Cells

Symptoms:

  • Clicking on cells doesn't activate edit mode
  • Cell appears non-editable
  • No cursor change on hover

Cause: The cell may contain a system field or the field type doesn't support inline editing.

Solution:

  1. System fields (id, createdAt, updatedAt, _deleted, _rev) are read-only by design
  2. Complex objects and arrays open in a content modal instead of inline editing
  3. Try using the edit button to open the full document form
  4. Check if you have write permissions for the collection

Issue: Filter Queries Return Wrong Results

Symptoms:

  • Filter applied but unexpected results appear
  • More or fewer results than expected
  • Filter seems to have no effect

Cause: Operator selection, value format, or field type mismatch.

Solution:

  1. Verify the operator matches your intent:
    • Use equals for exact matches
    • Use contains for partial text matches (case-sensitive)
    • Use exists / notExists for checking field presence
  2. Ensure value format matches field type:
    • Strings: Use text as-is
    • Numbers: Enter numeric values only
    • Booleans: Select from dropdown
    • Enums: Select from provided options
  3. Remember that filters are AND-combined (all conditions must match)
  4. Clear filters and re-add them one at a time to identify the issue

Issue: REST Mode Connection Failed

Symptoms:

  • Error message when switching to REST mode
  • "Connection refused" or timeout errors
  • Collections don't load in REST mode

Cause: RxDB Server may not be running or misconfigured.

Solution:

  1. Verify RxDB Server is running:

    yarn docker:logs  # Check server status

  2. Confirm server URL is correct in server configuration

  3. Verify authentication token is valid and not expired

  4. Check that Domain ID matches server configuration

  5. Ensure no firewall is blocking the connection

  6. Try accessing the server URL directly in browser to verify it responds

Issue: Document Save Fails

Symptoms:

  • Inline edit doesn't persist
  • Form submission shows error
  • Document appears to save but reverts

Cause: Validation errors, schema violations, or connection issues.

Solution:

  1. Check for validation error messages in the form
  2. Ensure required fields are filled in
  3. Verify field values match expected types:
    • Enum fields must use allowed values
    • Reference fields must contain valid IDs
  4. Check browser console for detailed error messages
  5. In REST mode, verify server connection is stable
  6. Try refreshing the page and re-editing

Issue: Cannot Delete Documents

Symptoms:

  • Delete button doesn't respond
  • Confirmation dialog appears but document remains
  • Batch delete fails silently

Cause: Permission issues, soft delete, or connection problems.

Solution:

  1. Verify you have delete permissions for the collection
  2. Note that FlowState uses soft delete - documents may appear removed but exist with _deleted: true
  3. Check browser console for error messages
  4. Refresh the page and verify deletion status
  5. In REST mode, ensure server connection is active

Issue: Pagination Not Working

Symptoms:

  • Page controls don't change displayed data
  • Same data appears on all pages
  • Page size selector has no effect

Cause: Usually a client-side state issue or data loading problem.

Solution:

  1. Refresh the page to reset pagination state
  2. Check if filters are affecting total result count
  3. Verify data exists beyond the first page
  4. In REST mode, pagination relies on server support - verify server is processing skip/limit

Issue: Document Form Shows Wrong Fields

Symptoms:

  • Form fields don't match expected schema
  • Missing required fields
  • Extra unexpected fields appear

Cause: Schema mismatch or caching issues.

Solution:

  1. Refresh the page to reload schemas
  2. Verify you're viewing the correct collection
  3. Check that schema definitions are up to date in the codebase
  4. Clear browser cache if schema recently changed

Performance Issues

Issue: Large Collections Load Slowly

Symptoms:

  • Long loading time when selecting collections
  • Browser becomes unresponsive
  • High memory usage

Cause: Large data sets being loaded into memory.

Solution:

  1. Use pagination - avoid loading more than 100 rows at once
  2. Apply filters to narrow down the data set before loading
  3. Use REST mode for large collections (server-side pagination)
  4. Consider using the CLI or MCP tools for bulk data operations

Issue: Inline Editing Feels Sluggish

Symptoms:

  • Delay between clicking and edit mode activating
  • Typing in edit mode lags
  • Saving takes a long time

Cause: Table re-rendering or database write performance.

Solution:

  1. Reduce page size to minimize re-rendering
  2. Close other FlowState apps to free resources
  3. Check if RxDB replication is syncing large amounts of data
  4. Use the document form modal for editing multiple fields at once

Getting Help

If you can't resolve your issue:

  1. Check the FAQ for additional answers
  2. Review the Features documentation for proper usage
  3. Contact support with:
    • Description of the issue
    • Steps to reproduce
    • Screenshots if applicable
    • Browser and device information
    • Connection mode (Local or REST)
    • Collection name and approximate document count
    • Any error messages from the browser console
Previous
Exploring Data
Next
FAQ