Breaking Update Notice

V2 is not a standard overwrite update. It replaces the data structure and adjusts the entry points and behavior for features such as Assistants, Agents, Knowledge Bases, Web Search, and Files.

V2 Can Migrate V1 Directly

If you need to retain V1 data, follow the V1.9.13 → V2 (direct data migration) process; no intermediate V2 release is required.

Current Status	Recommended Action
Still on V1, need to retain data	Update V1 to 1.9.13, create a full backup, then install V2 directly.
Already using V2	Upgrade to V2 normally and continue using your current V2 data.
Previous V1 migration failed or data was missed	First create a full backup of your current V2 data, then consider using [Re-migrate].
Do not need V1 data	You can select [Ignore and Use Defaults], but V1 data will not be migrated.

Required Before Upgrading

Update V1 to 1.9.13 and ensure it starts normally at least once.
Disable [Compact Backup] and create a full V1 backup.
Completely exit BLACK HOLE, then copy the entire V1 data directory.
If using a custom directory or external disk, ensure the path is mounted and readable/writable.

The migration wizard reads the current V1 data directory, not the backup ZIP. Backups are for emergency recovery and cannot replace the original data directory during migration.

[Re-migrate] Is Not Data Merging

V2 adds [Re-migrate] under [Settings] → [Data]. It is only for fixing cases where a previous V1 migration failed or data was missed.

Before proceeding, you must confirm the following:

Current V2 data will be permanently deleted and cannot be undone.
Original V1 data will be retained and re-imported after restart.
You must create a full backup of your current V2 data first.

A full backup does not automatically merge V1 and V2 data. If you need to retain new V2 content, export it separately or keep a full backup.

Key Checks After Upgrading

Model services, API Keys, and default models; Anthropic OAuth will not be migrated, so you must use an API Key.
Assistant groups, prompt order, Agent tool permissions, and Knowledge Base bindings.
Knowledge Base failure sources, Web Search keyword search, and URL reading services.
Custom CSS, sidebar favorites, and missing files.

See Feature Differences for a complete comparison.

Migration Failure or Rollback

Prefer using [Retry] to fix data directory, disk, or data issues and continue.
[Save Issue Info] saves only locally; the file may contain paths, content, or credentials. Share it only with the BLACK HOLE support team.
[Ignore and Use Defaults] starts from default configurations; V1 data will not be migrated.
Returning to V1 normally does not require deleting the database, and do not restore V2 backups to V1.

Continue Reading

Feature Differences

View automatic migrations, items requiring review, and content that will not be inherited.

V1 to V2 Upgrade

Complete backup, migration, and verification in the correct version order.

V2 to V1 Downgrade

Learn about rollback, backup, and database handling precautions.