v2rayA/v2rayA · error

failed to migrate touch bucket: %w

Error message

failed to migrate touch bucket: %w

What it means

This error is returned by MigrateFromBoltDB when the 'touch' BoltDB bucket (servers and subscriptions) could not be migrated to the SQLite servers/subscriptions tables. It wraps the underlying cause: invalid or non-array JSON in the servers/subscriptions keys, an INSERT failure for a server or subscription, or a LastInsertId failure. The transaction is rolled back and no subscription/server data is written.

Source

Thrown at service/db/migrate.go:76

	defer func() {
		if p := recover(); p != nil {
			_ = tx.Rollback()
			panic(p)
		}
	}()

	// Migrate system bucket
	if err := migrateSystemBucket(boltDB, tx); err != nil {
		_ = tx.Rollback()
		return fmt.Errorf("failed to migrate system bucket: %w", err)
	}

	// Migrate touch bucket (servers and subscriptions)
	// subIDMap maps BoltDB subscription index (0-based) -> SQLite subscription ID
	subIDMap, err := migrateTouchBucket(boltDB, tx)
	if err != nil {
		_ = tx.Rollback()
		return fmt.Errorf("failed to migrate touch bucket: %w", err)
	}

	// NOTE: Accounts are NOT migrated. Users must re-register after migration.
	// This is intentional: the old MD5-based password hashing is deprecated,
	// and requiring re-registration ensures users set up fresh bcrypt-based credentials.

	// Migrate outbounds bucket
	if err := migrateOutboundsBucket(boltDB, tx, subIDMap); err != nil {
		_ = tx.Rollback()
		return fmt.Errorf("failed to migrate outbounds bucket: %w", err)
	}

	// Commit transaction
	if err := tx.Commit(); err != nil {
		return fmt.Errorf("failed to commit migration transaction: %w", err)
	}

	// Verify data integrity

View on GitHub (pinned to 71e5442fc5)

Solutions

1. Read the wrapped cause: 'invalid JSON for servers', 'servers data is not an array', 'failed to insert server N', etc., to pinpoint the failing record.
2. Validate the JSON stored in the touch bucket (export it with bbolt tooling); repair or hand-fix malformed records in bolt.db or accept data loss for the bad record.
3. Remove the leftover v2raya.db and restart so migration retries cleanly after fixing the source data.
4. Check disk space and SQLite errors (disk I/O, constraint violations) in the wrapped message.
5. Restore bolt.db from a backup if the touch bucket is corrupt.

Example fix

// before: bolt.db 'subscriptions' value is corrupt JSON
// error: failed to migrate touch bucket: invalid JSON for subscriptions

// after: restore a known-good bolt.db before restarting
mv /etc/v2raya/bolt.db /etc/v2raya/bolt.db.corrupt
cp /backup/bolt.db /etc/v2raya/bolt.db  # then restart the service

// Go: pre-check the touch bucket JSON before migrating (read-only bbolt open)
boltDB.View(func(tx *bbolt.Tx) error {
    bkt := tx.Bucket([]byte("touch")); if bkt == nil { return nil }
    for _, k := range []string{"servers", "subscriptions"} {
        if v := bkt.Get([]byte(k)); v != nil && !gjson.ValidBytes(v) {
            return fmt.Errorf("touch/%s holds invalid JSON; repair bolt.db first", k)
        }
    }
    return nil
})

if err := db.MigrateFromBoltDB(); err != nil {
    if strings.Contains(err.Error(), "failed to migrate touch bucket") {
        // restore a known-good bolt.db, remove the partial sqlite db, retry
        log.Fatalf("touch bucket migration failed: %v", err)
    }
    return err
}

When it happens

Trigger: migrateTouchBucket returns an error: the bbolt View fails, the 'servers' or 'subscriptions' values are not valid JSON or not JSON arrays (gjson.ValidBytes/IsArray checks in migrateServers/migrateSubscriptions), an INSERT into servers/subscriptions fails, or res.LastInsertId() fails while building subIDMap.

Common situations: Upgrading v2rayA with a bolt.db whose touch bucket was corrupted by an earlier crash or by editing the file externally; JSON payloads that fail validation; SQLite constraint/schema problems on first run after upgrade; disk-full during the write-heavy server/subscription import.

Related errors

• bolt.db exists, migration required
• failed to migrate system bucket: %w
• failed to migrate outbounds bucket: %w
• migration verification failed: %w
• subscription count mismatch: BoltDB=%d, SQLite=%d

AI-assisted analysis of v2rayA/v2rayA@71e5442fc5 (2026-09-05). Data as JSON: /api/errors/9a400ce585a7a595. Report an issue: GitHub.