Configuration Migration Tool¶
Potato's migration tool upgrades a configuration file from an older format to v2. It detects what needs changing, applies it, and leaves your other settings alone.
Usage¶
# Basic migration (prints migrated config to stdout)
potato migrate config.yaml --to-v2
# Save to a new file
potato migrate config.yaml --to-v2 --output new_config.yaml
# Modify the original file in place
potato migrate config.yaml --to-v2 --in-place
# Preview changes without applying them
potato migrate config.yaml --to-v2 --dry-run
Command Options¶
| Option | Short | Description |
|---|---|---|
--to-v2 |
Required. Migrate to v2 format | |
--output FILE |
-o |
Write migrated config to specified file |
--in-place |
-i |
Modify the original config file directly |
--dry-run |
Show what changes would be made without applying them | |
--quiet |
-q |
Suppress informational output |
Note: --in-place and --output cannot be used together.
Migration Rules¶
The migration tool applies the following transformations:
1. Highlight to Span¶
Renames the legacy highlight annotation type to span. This is the most
common v1→v2 breaking change — a config that still uses highlight is rejected
at boot with Unknown annotation type: highlight. The rule rewrites every
scheme (top-level, per-phase, and training schemes).
Before:
annotation_schemes:
- annotation_type: "highlight"
name: "entities"
labels: ["PERSON", "ORG"]
After:
annotation_schemes:
- annotation_type: "span"
name: "entities"
labels: ["PERSON", "ORG"]
2. Textarea to Multiline¶
Converts the old textarea format to the new multiline format for text schemas.
Before:
annotation_schemes:
- annotation_type: "text"
name: "feedback"
textarea:
on: true
rows: 4
cols: 50
After:
annotation_schemes:
- annotation_type: "text"
name: "feedback"
multiline: true
rows: 4
cols: 50
3. Legacy User Config¶
Detects old user_config format and suggests adding explicit login configuration.
Before:
user_config:
allow_all_users: true
After:
user_config:
allow_all_users: true
login:
type: open
4. Label Requirement Format¶
Converts boolean label_requirement to the dictionary format.
Before:
annotation_schemes:
- annotation_type: "multirate"
name: "ratings"
label_requirement: true
After:
annotation_schemes:
- annotation_type: "multirate"
name: "ratings"
label_requirement:
required: true
5. Deprecated Output Format Key¶
Renames output_annotation_format, which nothing has read since the v2 storage rewrite:
- The value moves to
export_annotation_format, which writes a periodic export tooutput_annotation_dir/exports/<format>/ jsonbecomesjsonl, because the export registry has no exporter calledjson- An empty value, or a config that already sets
export_annotation_format, drops the old key without turning auto-export on
6. Site Configuration Notes¶
Confirms that site_dir: default is the recommended approach for v2, using auto-generated templates.
Examples¶
Preview Changes (Dry Run)¶
$ potato migrate old_config.yaml --to-v2 --dry-run
Migration changes:
[textarea_to_multiline] Convert textarea.on to multiline format in textbox schemas:
- Converted textarea.on to multiline in schema 'feedback'
[legacy_user_config] Migrate legacy user_config to login format:
- Added login.type: open (from allow_all_users: true)
- Note: user_config is still valid, login section added for clarity
Dry run - no changes written.
Migrated configuration would be:
annotation_task_name: My Task
...
Migrate and Save to New File¶
$ potato migrate old_config.yaml --to-v2 --output migrated_config.yaml
Migration changes:
...
Wrote migrated config to migrated_config.yaml
Quiet Mode¶
# Just output the migrated YAML, no status messages
$ potato migrate old_config.yaml --to-v2 --quiet > new_config.yaml
When to Use Migration¶
Consider using the migration tool when:
- Upgrading from an older version of Potato
- You see deprecation warnings when starting the server
- Configuration options don't work as expected
- You want to ensure your config follows current best practices
Troubleshooting¶
"Configuration file is empty"¶
The YAML file couldn't be parsed or is empty. Check that: - The file exists and is readable - The YAML syntax is valid - The file contains configuration content
"Invalid YAML in configuration file"¶
There's a syntax error in your YAML. Common issues: - Incorrect indentation - Missing colons after keys - Unquoted special characters
No migrations needed¶
If you see "No migrations needed - config is already up to date", your configuration already uses the current v2 format.