# Troubleshooting Common Dolt Errors: Database Locks, Commit Failures, and Transaction Conflicts

> Troubleshoot common Dolt errors like database locks, commit failures, and transaction conflicts. Learn to programmatically detect and handle these errors for robust application logic.

- Repository: [DoltHub/dolt](https://github.com/dolthub/dolt)
- Tags: troubleshooting
- Published: 2026-03-14

---

**Dolt surfaces runtime failures as exported Go error constants—such as `ErrDatabaseLocked`, `ErrCommitNotFound`, and `ErrRetryTransaction`—that you can detect programmatically using `errors.Is()` to implement retries, conflict resolution, and recovery logic.**

Dolt is a version-controlled SQL database implemented in Go. When operations fail—whether from concurrent access, corrupt storage, or schema violations—the engine returns specific error values defined across the codebase. Understanding where these errors originate and how to handle them enables you to debug CLI failures, automate recovery in Go clients, and maintain data integrity.

## Resolving Database Locks and Storage Corruption

Database-level errors in Dolt typically stem from the Node-Block-Store (NBS) storage layer or file-system operations. These errors indicate exclusive access conflicts or data integrity issues that require immediate attention.

**`ErrDatabaseLocked`** indicates that a second Dolt instance attempted to open a repository that already holds an active write lock. According to the Dolt source code, this error is defined in [`go/store/nbs/journal.go#L42`](https://github.com/dolthub/dolt/blob/main/go/store/nbs/journal.go#L42). This occurs when another `dolt push` or `dolt commit` process is running concurrently.

**`ErrInvalidTableFile`** and **`ErrTableFileNotFound`** represent low-level storage failures. The former, defined in [`go/store/nbs/table_reader.go#L134`](https://github.com/dolthub/dolt/blob/main/go/store/nbs/table_reader.go#L134), signals malformed data often caused by disk crashes or interrupted imports. The latter, from [`go/store/nbs/file_table_reader.go#L39`](https://github.com/dolthub/dolt/blob/main/go/store/nbs/file_table_reader.go#L39), indicates missing table files referenced in the manifest.

**`ErrMissingChunk`** ([`go/store/chunks/errors.go#L24`](https://github.com/dolthub/dolt/blob/main/go/store/chunks/errors.go#L24)) and **`ErrCorruptManifest`** ([`go/store/nbs/manifest.go#L38`](https://github.com/dolthub/dolt/blob/main/go/store/nbs/manifest.go#L38)) suggest repository corruption or incomplete clones. A missing chunk occurs when the chunk-store cannot locate a requested hash, while a corrupt manifest indicates JSON unmarshaling failures from disk truncation.

### Handling Database Lock Conflicts

In Go applications, detect these errors using standard error wrapping:

```go
import (
    "errors"
    nbs "github.com/dolthub/dolt/go/store/nbs"
)

if errors.Is(err, nbs.ErrDatabaseLocked) {
    // Retry after backoff or prompt user to close other sessions
    time.Sleep(2 * time.Second)
    continue
}
if errors.Is(err, nbs.ErrInvalidTableFile) {
    // Suggest dolt reset --hard or fresh clone
}

```

For CLI users encountering the lock error:

```bash
$ dolt sql -q "SELECT * FROM mytable"
Error: the database is locked by another dolt process

# Resolve by terminating the other process or waiting, then retry

```

## Fixing Commit and Branch Resolution Failures

When working with Dolt's version control features, operations may fail due to invalid references or branch state issues.

**`ErrCommitNotFound`** ([`go/store/datas/commit.go#L61`](https://github.com/dolthub/dolt/blob/main/go/store/datas/commit.go#L61)) occurs when a supplied commit hash does not exist in repository history. This typically indicates a typo or missing remote fetch.

**`ErrDBUpToDate`** ([`go/store/datas/pull/puller.go#L40`](https://github.com/dolthub/dolt/blob/main/go/store/datas/pull/puller.go#L40)) signals that `dolt pull` is a no-op because local history already matches the remote.

**`ErrEmptyBranchName`** ([`go/libraries/doltcore/sqle/dprocedures/dolt_checkout.go#L38`](https://github.com/dolthub/dolt/blob/main/go/libraries/doltcore/sqle/dprocedures/dolt_checkout.go#L38)) triggers when attempting to checkout an empty string, while **`ErrInvalidDatasetID`** ([`go/store/datas/database_common.go#L132`](https://github.com/dolthub/dolt/blob/main/go/store/datas/database_common.go#L132)) indicates a malformed database-branch combination identifier.

To handle missing commits in Go clients:

```go
commit, err := ds.GetCommit(ctx, hash)
if err != nil {
    if errors.Is(err, datas.ErrCommitNotFound) {
        fmt.Printf("Commit %s does not exist – did you mistype the hash?\n", hash)
        return
    }
    // Handle other errors
}

```

## Handling Transaction Conflicts and Retry Logic

Dolt uses optimistic concurrency control, which requires specific error handling for write conflicts.

**`ErrRetryTransaction`** ([`go/libraries/doltcore/sqle/dsess/transactions.go#L45`](https://github.com/dolthub/dolt/blob/main/go/libraries/doltcore/sqle/dsess/transactions.go#L45)) indicates that a transaction conflicts with a committed transaction from another client. Your application must retry the operation.

**`ErrUnresolvedConflictsCommit`** ([`go/libraries/doltcore/sqle/dsess/transactions.go#L47`](https://github.com/dolthub/dolt/blob/main/go/libraries/doltcore/sqle/dsess/transactions.go#L47)) and **`ErrUnresolvedConflictsAutoCommit`** ([`go/libraries/doltcore/sqle/dsess/transactions.go#L49`](https://github.com/dolthub/dolt/blob/main/go/libraries/doltcore/sqle/dsess/transactions.go#L49)) occur when attempting to commit with unresolved merge conflicts in the `dolt_conflicts` tables. The autocommit variant aborts automatically unless `@@dolt_allow_commit_conflicts` is enabled.

**`ErrDirtyWorkingSets`** ([`go/libraries/doltcore/sqle/dsess/session.go#L561`](https://github.com/dolthub/dolt/blob/main/go/libraries/doltcore/sqle/dsess/session.go#L561)) prevents commits that span multiple branches or databases simultaneously.

Implement exponential backoff for transaction retries:

```go
for attempts := 0; attempts < 3; attempts++ {
    err = db.Commit(ctx, sql.NewCommitOptions())
    if err == nil {
        break
    }
    if errors.Is(err, dsess.ErrRetryTransaction) {
        time.Sleep(time.Duration(attempts+1) * time.Second)
        continue
    }
    log.Fatalf("Commit failed: %v", err)
}

```

For CLI conflict resolution:

```bash
$ dolt merge feature_branch

# ... conflicts detected ...

$ dolt conflicts resolve --all
$ dolt commit -m "Merge feature_branch"

```

## Schema Validation and Table Definition Errors

Dolt enforces strict naming conventions and schema compatibility rules.

**`ErrInvalidTableName`** and **`ErrReservedTableName`** ([`go/libraries/doltcore/sqle/database.go#L61-L62`](https://github.com/dolthub/dolt/blob/main/go/libraries/doltcore/sqle/database.go#L61)) prevent creating tables with invalid identifiers or names beginning with the reserved `dolt_` prefix.

**`ErrPrimaryKeySetsIncompatible`** ([`go/libraries/doltcore/alterschema.go#L147`](https://github.com/dolthub/dolt/blob/main/go/libraries/doltcore/alterschema.go#L147)) triggers when attempting to alter primary key definitions on tables containing existing data.

**`ErrColTagCollision`** ([`go/libraries/doltcore/schema/col_coll.go#L25`](https://github.com/dolthub/dolt/blob/main/go/libraries/doltcore/schema/col_coll.go#L25)) indicates that imported schema definitions contain duplicate internal column tags.

Example validation in Go:

```go
_, err := sess.CreateTable(ctx, "dolt_mytable", schema)
if err != nil && errors.Is(err, sql.ErrReservedTableName) {
    log.Fatalf("You cannot name a table with the dolt_ prefix.")
}

```

## Configuration and Filesystem Issues

Environment setup errors surface when Dolt cannot locate required files or configuration parameters.

**`ErrNoConfig`** ([`go/store/config/config.go#L65`](https://github.com/dolthub/dolt/blob/main/go/store/config/config.go#L65)) and **`ErrConfigParamNotFound`** ([`go/libraries/utils/config/config.go#L23`](https://github.com/dolthub/dolt/blob/main/go/libraries/utils/config/config.go#L23)) indicate missing [`.dolt/config.json`](https://github.com/dolthub/dolt/blob/main/.dolt/config.json) files or unset required keys like `user.name`.

**`ErrIsDir`** and **`ErrDirNotExist`** ([`go/libraries/utils/filesys/fs.go#L27-L29`](https://github.com/dolthub/dolt/blob/main/go/libraries/utils/filesys/fs.go#L27)) occur when operations expect files but receive directories, or when the `.dolt` repository folder is missing.

Resolve configuration errors via CLI:

```bash
$ dolt config --global --add user.name "Alice"
$ dolt config --global --add user.email "alice@example.com"

```

## Programmatic Error Detection Patterns

When building applications with Dolt's Go SDK, wrap CLI calls or database operations to detect specific error states and implement recovery logic.

### Detecting Repository Locks in CLI Wrappers

```go
package main

import (
    "errors"
    "fmt"
    "os/exec"
    "strings"
    "time"

    nbs "github.com/dolthub/dolt/go/store/nbs"
)

func runDolt(args ...string) error {
    cmd := exec.Command("dolt", args...)
    out, err := cmd.CombinedOutput()
    if err != nil {
        if strings.Contains(string(out), nbs.ErrDatabaseLocked.Error()) {
            return nbs.ErrDatabaseLocked
        }
        return fmt.Errorf("%w: %s", err, out)
    }
    fmt.Print(string(out))
    return nil
}

func main() {
    for i := 0; i < 5; i++ {
        if err := runDolt("sql", "-q", "SELECT * FROM mytable"); err != nil {
            if errors.Is(err, nbs.ErrDatabaseLocked) {
                fmt.Println("Repo is locked – retrying in 2 seconds...")
                time.Sleep(2 * time.Second)
                continue
            }
            fmt.Printf("Command failed: %v\n", err)
            break
        }
        break
    }
}

```

### Recovering from Missing Commits

```go
hash := "c5b8e7b..."
commit, err := ds.GetCommit(ctx, hash)
if err != nil {
    if errors.Is(err, datas.ErrCommitNotFound) {
        fmt.Printf("Commit %s not found – fetching from remote.\n", hash)
        if pullErr := ds.Pull(ctx, remoteRef); pullErr != nil {
            log.Fatalf("Pull failed: %v", pullErr)
        }
        commit, err = ds.GetCommit(ctx, hash) // Retry once
    }
    if err != nil {
        log.Fatalf("Unable to retrieve commit: %v", err)
    }
}

```

### Robust Transaction Committing

```go
func commitWithRetry(db *sql.Engine) error {
    const maxAttempts = 3
    for i := 0; i < maxAttempts; i++ {
        err := db.Commit(context.Background(), sql.NewCommitOptions())
        if err == nil {
            return nil
        }
        if errors.Is(err, dsess.ErrRetryTransaction) {
            fmt.Println("Conflict detected – retrying transaction")
            continue
        }
        return fmt.Errorf("commit failed: %w", err)
    }
    return fmt.Errorf("max retry attempts reached")
}

```

## Summary

- Most Dolt failures surface as well-named exported `error` variables defined in specific source files like [`go/store/nbs/journal.go`](https://github.com/dolthub/dolt/blob/main/go/store/nbs/journal.go) and [`go/libraries/doltcore/sqle/dsess/transactions.go`](https://github.com/dolthub/dolt/blob/main/go/libraries/doltcore/sqle/dsess/transactions.go).
- Use `errors.Is()` rather than string matching to reliably detect `ErrDatabaseLocked`, `ErrRetryTransaction`, and other specific failure modes.
- Database locks require process termination or backoff delays, while transaction conflicts need retry loops with exponential backoff.
- Repository corruption errors like `ErrInvalidTableFile` or `ErrMissingChunk` typically require `dolt reset --hard` or fresh clones.
- Schema errors prevent invalid table creation at the API level, allowing validation before data insertion.

## Frequently Asked Questions

### How do I fix "database is locked" errors in Dolt?

The `ErrDatabaseLocked` error from [`go/store/nbs/journal.go`](https://github.com/dolthub/dolt/blob/main/go/store/nbs/journal.go) indicates another Dolt process holds an exclusive write lock on the repository. Terminate the competing process (such as another `dolt sql` session or active commit), wait a few seconds for the lock to release, then retry your operation. In automated scripts, implement a retry loop with 2-second backoff intervals.

### What causes "missing chunk" errors and how do I recover?

`ErrMissingChunk` defined in [`go/store/chunks/errors.go`](https://github.com/dolthub/dolt/blob/main/go/store/chunks/errors.go) occurs when the storage layer cannot locate a chunk hash referenced in the manifest, usually due to incomplete clones, disk corruption, or manually deleted table files. Recovery typically requires running `dolt reset --hard` to restore the working set to the last valid commit, or performing a fresh clone from a remote repository to restore missing data files.

### How do I handle merge conflicts programmatically in Dolt?

When `dolt merge` produces conflicts, Dolt returns `ErrUnresolvedConflictsCommit` from [`go/libraries/doltcore/sqle/dsess/transactions.go`](https://github.com/dolthub/dolt/blob/main/go/libraries/doltcore/sqle/dsess/transactions.go). Your application must query the `dolt_conflicts` tables to identify conflicting rows, execute `dolt conflicts resolve` for each table or use `--all` flag in CLI, and then retry the commit. In autocommit mode, set `@@dolt_allow_commit_conflicts` to prevent automatic rollback while resolving conflicts manually.

### Why does Dolt report "target commit not found"?

`ErrCommitNotFound` from [`go/store/datas/commit.go`](https://github.com/dolthub/dolt/blob/main/go/store/datas/commit.go) triggers when referencing a commit hash that does not exist in the local repository history. This commonly occurs when referencing commits from unpulled remote branches or typographical errors in hash strings. Resolve by fetching the latest changes via `dolt fetch` or `dolt pull`, or verify the hash reference for accuracy.