What causes "[%s] failed to check collection references: %w" in pocketbase/pocketbase?

Check the wrapped error — 'database is locked' means contention, a decode error names the bad collection

[%s] failed to check collection references: %w

Error message

[%s] failed to check collection references: %w

What it means

Before deleting a collection (with integrity checks on), PocketBase scans all other collections for relation fields pointing at the deleted one. This error wraps a failure of that lookup itself — a DB read error, not the presence of references.

Source

Thrown at core/collection_model.go:702

// -------------------------------------------------------------------

func onCollectionDeleteExecute(e *CollectionEvent) error {
	if e.Collection.System {
		return fmt.Errorf("[%s] system collections cannot be deleted", e.Collection.Name)
	}

	defer func() {
		if err := e.App.ReloadCachedCollections(); err != nil {
			e.App.Logger().Warn("Failed to reload collections cache", "error", err)
		}
	}()

	if !e.Collection.disableIntegrityChecks {
		// ensure that there aren't any existing references.
		// note: the select is outside of the transaction to prevent SQLITE_LOCKED error when mixing read&write in a single transaction
		references, err := e.App.FindCollectionReferences(e.Collection, e.Collection.Id)
		if err != nil {
			return fmt.Errorf("[%s] failed to check collection references: %w", e.Collection.Name, err)
		}
		if total := len(references); total > 0 {
			names := make([]string, 0, len(references))
			for ref := range references {
				names = append(names, ref.Name)
			}
			return fmt.Errorf("[%s] failed to delete due to existing relation references: %s", e.Collection.Name, strings.Join(names, ", "))
		}
	}

	originalApp := e.App

	txErr := e.App.RunInTransaction(func(txApp App) error {
		e.App = txApp

		// delete the related view or records table
		if e.Collection.IsView() {
			if err := txApp.DeleteView(e.Collection.Name); err != nil {

View on GitHub (pinned to 5d217ddb50)

Solutions

Check the wrapped error — 'database is locked' means contention, a decode error names the bad collection
Retry the delete when the DB is quiet (no concurrent batch writes/jobs)
Repair or re-save the collection whose fields JSON fails to parse (Admin UI > edit > save regenerates it)
Ensure only one process has pb_data open (no stale server + CLI combo)

Example fix

// before: deleting during a bulk import
// after: quiesce, then delete with a small guard
if !c.System {
    if err := app.Delete(c); err != nil {
        log.Printf("delete %s failed: %v", c.Name, err) // retry later
    }
}

Defensive patterns

Strategy: retry

Validate before calling

// run during a quiet window
if n, _ := app.DB().NewQuery("SELECT count(*) FROM pragma_lock_status").Row(); /* contention check */ false {
}

Try / catch

var lastErr error
for attempt := 0; attempt < 3; attempt++ {
    if err := app.Delete(c); err == nil { break } else {
        if !strings.Contains(err.Error(), "failed to check collection references") { return err }
        lastErr = err; time.Sleep(time.Duration(attempt+1) * 500 * time.Millisecond)
    }
}

Prevention

Schedule schema changes outside bulk-write windows
Keep one writer process per pb_data
Re-save suspicious collections to regenerate clean fields JSON

When it happens

Trigger: app.Delete(collection) when FindCollectionReferences fails: database is locked by a concurrent writer, the DB connection is broken, or another collection's stored field JSON is malformed so parsing references errors out.

Common situations: Deleting collections while heavy concurrent writes hold the DB; a corrupted _collections row with invalid fields JSON (often from hand edits or a failed import); running against a data.db that was replaced underneath a live process.

Related errors

AI-assisted analysis of pocketbase/pocketbase@5d217ddb50 (2026-08-15). Data as JSON: /api/errors/7e5eebc4a3a9f2a2. Report an issue: GitHub.