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

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. 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, signals malformed data often caused by disk crashes or interrupted imports. The latter, from go/store/nbs/file_table_reader.go#L39, indicates missing table files referenced in the manifest.

ErrMissingChunk (go/store/chunks/errors.go#L24) and ErrCorruptManifest (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:

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:

$ 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) 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) 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) triggers when attempting to checkout an empty string, while ErrInvalidDatasetID (go/store/datas/database_common.go#L132) indicates a malformed database-branch combination identifier.

To handle missing commits in Go clients:

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) 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) and ErrUnresolvedConflictsAutoCommit (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) prevents commits that span multiple branches or databases simultaneously.

Implement exponential backoff for transaction retries:

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:

$ 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) prevent creating tables with invalid identifiers or names beginning with the reserved dolt_ prefix.

ErrPrimaryKeySetsIncompatible (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) indicates that imported schema definitions contain duplicate internal column tags.

Example validation in 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) and ErrConfigParamNotFound (go/libraries/utils/config/config.go#L23) indicate missing .dolt/config.json files or unset required keys like user.name.

ErrIsDir and ErrDirNotExist (go/libraries/utils/filesys/fs.go#L27-L29) occur when operations expect files but receive directories, or when the .dolt repository folder is missing.

Resolve configuration errors via CLI:

$ 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

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

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

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 and 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 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 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. 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}