Troubleshooting OUTDATED_SCHEMA Error

If you encounter an OUTDATED_SCHEMA error in your environment, it may be due to an interrupted ledger creation process or modifications to the schema. This article will guide you through the troubleshooting steps.

Possible Causes

• Interrupted ledger creation process

• Modifications of the version of the schema by an internal process

• Inconsistencies between the applied schema and migration tables

Troubleshooting Steps

1. Check OpenTelemetry Traces

If you have OpenTelemetry traces enabled, review them to identify any issues during the ledger creation process.

2. Inspect the migration table from your tool if any

For instance, when using Goose - a database migration tool. It manages your database schema by creating incremental SQL changes or Go functions.

Any modifications to default migration table goose_db_version could potentially cause the OUTDATED_SCHEMA error.

3. Review Migration Tables and Applied Schema

If possible, compare the migration tables with the actually applied schema to identify any inconsistencies.

Resolution

If you've identified the issue and it's on your side, take appropriate action to resolve it. This may involve:

• Correcting any interrupted ledger creation processes

• Fixing modifications made to migration tables

• Ensuring consistency between migration tables and applied schemas

The overall process of creating a ledger is not atomic.

There is some edge conditions where a ledger can be created, and the schema not.
For example, if the creation of a ledger is interupted by the user or a connection is dropped.

If the process was stopped while it was being created, nothing is done automatically, to avoid the risk of losing data or other information. Then you'll have to do the following manual steps:

• delete the associated schema

• deleting the entry in the ledgers table of the _system schema

• run the migration command again

Last Resort: Dropping and Recreating Schemas

If you're unable to resolve the issue through the above steps, you may need to drop and recreate your schemas. However, this should be considered a last resort:

1. Back up your existing schemas and data if possible

2. Drop all schemas (including entries in the ledgers table of the _system schema)

3. Recreate your schemas and ledgers

Prevention

To prevent this issue in the future:

• Avoid manual modifications to schema-related tables

• Ensure ledger creation processes complete without interruption

• Regularly back up your databases before making significant changes

If you continue to experience issues after following these steps, please contact our support team for further assistance.