Troubleshoot CouchDB

Migrating G Suite data can consume a large amount of disk space. Although you get guidance when setting up G Suite Migrate on how much disk space you need, you might find that the Apache CouchDB software consumes all available disk space and is no longer functioning.

You can use this article to troubleshoot a full disk on CouchDB.

Monitor the CouchDB disk

You should periodically monitor the CouchDB disk to track usage. If you cannot monitor the disk manually, look for these indications that CouchDB is not functioning correctly:

  • Detailed bridge transaction information is not accessible.
  • Bridge partitions fail to launch.
  • CouchDB administration page (http://localhost:5984/_utils or equivalent address based on your configuration) does not load.
  • Service Host Log from the G Suite Migrate platform or node server displays CouchDB errors with the following strings:
    • badarg
    • unknown_error
    • function_clause

    For details on Service Host Log locations, see Still need help? in Troubleshoot G Suite Migrate.

Resolve CouchDB disk errors

If CouchDB experiences a crash, you need to start it again.

After you restart, try these options to resolve the errors.

Open all   |   Close all

Option 1: Increase the disk size
To complete this task, determine where CouchDB is installed. How you increase the disk size varies depending on the hardware used for the CouchDB database.
  • Move files from a single CouchDB node to a new, larger disk. If you don’t move files to the new disk, you’ll lose the existing data on the database. For details, consult your CouchDB documentation.
  • Google Cloud Platform (GCP) might also support increasing the disk size. With GCP, the instance's main boot disk (the one containing the operating system) has a maximum size of 2 TB while persistent or attached disks can be much larger than this. For this reason, our installation guide recommends separate (attached) disks. For details on resizing persistent disks, see Adding or Resizing Zonal Persistent Disks.

Option 2: Delete old data

If you have old projects that you no longer need, you can delete them to free up space.

Additionally, if you have CouchDB data associated with previous bridge transaction logs, you can clear the data by following these steps:

  1. Go to http://localhost:5131/#/clear-transaction-details (or equivalent address based on your configuration).
  2. Select the bridges to clear and click Delete "".

  3. (Optional) To retain transaction detail information from the most recent execution of each bridge, select Preserve details from most recent executions.

    Note: This option clears a CouchDB disk that's full from running one bridge multiple times. If you run all your bridges at one time, we do not recommend selecting this setting as you will not free up space on the disk. When this option is not selected, all transaction detail information for the selected bridges is cleared while the transaction records are retained.

  4. Click Yes to start the process.

  5. Click Details "" to verify the bridge transaction logs are empty. The transaction detail information for the selected bridges should show No items to display.
  6. Recheck CouchDB’s disk usage to make sure sufficient disk space is present. For details on CouchDB disk space requirements, see System requirements.

Prevent a CouchDB full disk

If space is still a concern after increasing your disk size and removing old data, you can reduce the amount of transaction detail logged to prevent a full disk on CouchDB. To do this, you need to change a setting that is currently only accessible in MySQL.

Note: When less data is being logged, troubleshooting can be more difficult. To see more detailed information, increase the logging level and run a delta migration.

To adjust the transaction detail logging level:

  1. Open MySQL Workbench or a similar tool that connects to a MySQL database.
  2. Go to the keyvalues_global database and find the settings table.
  3. In the table, find the _Key row, which is set to TransactionDetailsLoggingLevel.
  4. Locate the _Value property for the _Key. It should be set to one of the following values:
    • All—No restrictions are placed on transaction details logging.
    • ErrorsAndWarnings—Only details for entries marked as a warning or error are logged (Default).
    • ErrorsOnly—Only details for entries marked as an error are logged.
  5. Set the new transaction detail logging level using the following query: UPDATE keyvalues_global.settings SET _Value = '{variable}' WHERE _Key = 'TransactionDetailsLoggingLevel'.
  6. Depending on which logging level you want, replace {variable} with one of these case-sensitive values:
    • All
    • ErrorsAndWarnings
    • ErrorsOnly

    To minimize the amount of transaction detail data, we recommend ErrorsOnly.

Note: It can take up to 10 minutes for this setting to take effect.

Related topics

Google, Google Workspace, and related marks and logos are trademarks of Google LLC. All other company and product names are trademarks of the companies with which they are associated.