> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/troubleshooting/databases/mariadb-snapshot-isolation.md).

# MariaDB "Record has changed since last read" errors

MariaDB snapshot-isolation write conflicts (error 1020 / ER\_CHECKREAD), how OpenIAM retries them automatically, and how to tune the retry.

| Symptom                                                                     | Likely cause                                                          | Resolution                                                                                |
| --------------------------------------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `ErrorCode: 1020` / `ER_CHECKREAD` in a service log, and the API call fails | Two requests wrote the same rows at once, and MariaDB rolled one back | None needed — OpenIAM retries it. [Tune the retry](#solution) if it exhausts its attempts |

## Problem

On MariaDB 11.6.2 and later, OpenIAM services may log database errors such as the following, and the corresponding API call returns a failure.

```
ErrorCode: 1020, SQLState: HY000
Record has changed since last read in table 'AUTH_STATE'; try restarting transaction
```

The table name varies — the error can appear for any table that is written concurrently by more than one request.

This applies both to an existing MariaDB server of 11.6.2 or later that you connect OpenIAM to, and to a default installation: OpenIAM installs **MariaDB 11.8.8**, which is within that range.

## Cause

MariaDB enabled `innodb_snapshot_isolation` by default in version 11.6.2. Under the REPEATABLE READ isolation level, a transaction that writes a row which changed after the transaction's read view was taken now fails with error 1020 (`ER_CHECKREAD`) instead of proceeding silently, as older MariaDB versions did. Nothing is committed — the transaction rolls back, and MariaDB expects the application to run it again, the same way it would after a deadlock or a lock wait timeout.

This is a behavior change in the database, not a data problem. It surfaces under concurrent load, when two requests write the same rows at nearly the same time.

## Solution

OpenIAM retries these rolled-back transactions automatically. When a service processes a request and the database reports a write conflict — error 1020, a deadlock, or a lock wait timeout — the operation is run again on a fresh transaction. Only these conflict errors are retried; business validation failures and other errors are returned to the caller immediately.

The retry can be tuned with the following properties, set the same way as any other OpenIAM application property — see [Overriding UI application properties](/troubleshooting/interface/overriding-app-properties.md) for the mechanics of overriding properties per installation type, and [Where settings live](/administration-guide/start/where-settings-live.md) for which source wins when a setting is defined in more than one place.

{% code overflow="wrap" %}

```properties
# Total attempts, including the first one. 1 disables retrying. Default: 3
org.openiam.db.conflict.retry.max.attempts=3

# Pause before each retry in milliseconds, multiplied by the attempt number. 0 disables the pause. Default: 50
org.openiam.db.conflict.retry.backoff.millis=50
```

{% endcode %}

A retried conflict is logged at WARN level:

```
Database write conflict on attempt 1 of 3, retrying: ...
```

{% hint style="info" %}
Seeing this warning occasionally under load is normal and requires no action. If a specific operation exhausts all attempts repeatedly, that points to sustained contention on the same rows, and the workload or the number of attempts should be reviewed.
{% endhint %}

{% hint style="warning" %}
Disabling `innodb_snapshot_isolation` on the database server also makes the errors disappear, but this only restores the older, less safe concurrency behavior that the new default was introduced to correct. It is not recommended as a long-term fix.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openiam.com/troubleshooting/databases/mariadb-snapshot-isolation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.