What causes "error creating file history: %w" in charmbracelet/crush?

Ensure the session ID in the context corresponds to a real persisted session.

error creating file history: %w

Error message

error creating file history: %w

What it means

After a successful write, the tool records the file's prior content in a per-session file history (files.Create). If the record cannot be created (DB error, session not persisted, constraint failure), the tool returns this wrapped error — notably the file write itself has already succeeded, but the operation reports failure.

Source

Thrown at internal/agent/tools/write.go:148

					Diff:      diff,
					Additions: additions,
					Removals:  removals,
				})
				return resp, nil
			}

			err = os.WriteFile(filePath, []byte(params.Content), 0o644)
			if err != nil {
				return fantasy.ToolResponse{}, fmt.Errorf("error writing file: %w", err)
			}

			// Check if file exists in history
			file, err := files.GetByPathAndSession(ctx, filePath, sessionID)
			if err != nil {
				_, err = files.Create(ctx, sessionID, filePath, oldContent)
				if err != nil {
					// Log error but don't fail the operation
					return fantasy.ToolResponse{}, fmt.Errorf("error creating file history: %w", err)
				}
			}
			if file.Content != oldContent {
				// User manually changed the content; store an intermediate version
				_, err = files.CreateVersion(ctx, sessionID, filePath, oldContent)
				if err != nil {
					slog.Error("Error creating file history version", "error", err)
				}
			}
			// Store the new version
			_, err = files.CreateVersion(ctx, sessionID, filePath, params.Content)
			if err != nil {
				slog.Error("Error creating file history version", "error", err)
			}

			filetracker.RecordRead(ctx, sessionID, filePath)

			notifyLSPs(ctx, lspManager, params.FilePath)

View on GitHub (pinned to 7944b8e522)

Solutions

Ensure the session ID in the context corresponds to a real persisted session.
Check SQLite lock contention / concurrent writers; retry or serialize writes.
Verify the database is writable and has disk space.
Run pending DB migrations to keep the schema consistent.

Example fix

// before
ctx := agent.WithSession(context.Background(), "nonexistent-session")
tool.Run(ctx, params)

// after
sess, _ := app.Sessions.Create(ctx, agent.DefaultSessionName)
ctx := agent.WithSession(ctx, sess.ID)
tool.Run(ctx, params)

Defensive patterns

Strategy: retry

Validate before calling

if sess, err := app.Sessions.Get(ctx, sessionID); err != nil {
    return fmt.Errorf("session %s not persisted; history recording will fail", sessionID)
}

Try / catch

if err != nil {
    if strings.Contains(err.Error(), "database is locked") {
        time.Sleep(100 * time.Millisecond)
        // retry the tool call once
    }
    return err
}

Prevention

Only use session IDs returned by Sessions.Create — never fabricated ones.
Enable SQLite busy_timeout / WAL mode to reduce lock errors.
Ensure the DB directory has free disk space and write permission.

When it happens

Trigger: files.Create fails when the session ID in context does not exist in the sessions table (FK/constraint), the SQLite database is locked or read-only, or the DB migration state is inconsistent.

Common situations: Running the tool with a fabricated/foreign session ID against the real DB; SQLite 'database is locked' under concurrent writers; disk full preventing DB writes; opening the DB read-only.

Related errors

AI-assisted analysis of charmbracelet/crush@7944b8e522 (2026-08-29). Data as JSON: /api/errors/82935f5cb756f8af. Report an issue: GitHub.