config.yaml embedings_url fantasia initialize error

[EricDeveaud]

Hello,

when starting an ab-inition fantasia run

using provided config.yaml fantasia initialize exit with KeyError: 'embeddings_url

2026-03-06 13:15:34,640 - FANTASIA - INFO - PostgreSQL connection OK.
2026-03-06 13:15:34,643 - FANTASIA - INFO - RabbitMQ connection OK.
2026-03-06 13:15:34,643 - FANTASIA - INFO - Starting initialization...
Traceback (most recent call last):
  File "/opt/gensoft/exe/FANTASIA/4.1.1/venv/bin/fantasia", line 8, in <module>
    sys.exit(main())
             ^^^^^^
  File "/opt/gensoft/exe/FANTASIA/4.1.1/venv/lib/python3.12/site-packages/fantasia/main.py", line 424, in main
    initialize(conf)
  File "/opt/gensoft/exe/FANTASIA/4.1.1/venv/lib/python3.12/site-packages/fantasia/main.py", line 90, in initialize
    filename = os.path.basename(urllib.parse.urlparse(conf["embeddings_url"]).path)
                                                      ~~~~^^^^^^^^^^^^^^^^^^
KeyError: 'embeddings_url'

while config file claims
# Leave empty to skip the preload step.

what did I missed

regards

Eric

[frapercan]

Hello Eric,

You are right — I tested it on my side and I get exactly the same error:

frapercan@bioxaxi:~/PycharmProjects/FANTASIA411$ fantasia initialize
2026-03-06 14:12:57,553 - FANTASIA - INFO - PostgreSQL connection OK.
2026-03-06 14:12:57,562 - FANTASIA - INFO - RabbitMQ connection OK.
2026-03-06 14:12:57,562 - FANTASIA - INFO - Starting initialization...
Traceback (most recent call last):
  File "/home/frapercan/.cache/pypoetry/virtualenvs/fantasia-eqn5pfVE-py3.12/bin/fantasia", line 6, in <module>
    sys.exit(main())
             ^^^^^^
  File "/home/frapercan/PycharmProjects/FANTASIA411/fantasia/main.py", line 424, in main
    initialize(conf)
  File "/home/frapercan/PycharmProjects/FANTASIA411/fantasia/main.py", line 90, in initialize
    filename = os.path.basename(urllib.parse.urlparse(conf["embeddings_url"]).path)
                                                      ~~~~^^^^^^^^^^^^^^^^^^
KeyError: 'embeddings_url'

The good news is that the workaround is straightforward.

From the CLI help:

(fantasia-py3.12) frapercan@bioxaxi:~/PycharmProjects/FANTASIA411$ fantasia initialize --help
usage: fantasia initialize [-h] [--config CONFIG] [--embeddings_url EMBEDDINGS_URL] [--base_directory BASE_DIRECTORY] [--log_path LOG_PATH]

Initialize FANTASIA environment:
 - Read YAML configuration.
 - Download the reference embeddings dump (if URL provided).
 - Ensure base directories exist.

Use --embeddings_url to override the dataset URL from YAML.

options:
  -h, --help            show this help message and exit
  --config CONFIG       Path to the YAML configuration file. Default: './fantasia/config.yaml'.
  --embeddings_url EMBEDDINGS_URL
                        Override the embeddings dump URL (otherwise taken from YAML).
  --base_directory BASE_DIRECTORY
                        Base directory used to place the embeddings/experiments folders.
  --log_path LOG_PATH   Path or directory for logs. If a directory, a 'Logs_<timestamp>.log' file is created inside.

Examples:
  Initialize with default from YAML (Final layer only)
  fantasia initialize --config ./fantasia/config.yaml

  Explicitly use Final layer only (smaller, faster)
  fantasia initialize --config ./fantasia/config.yaml \
    --embeddings_url https://zenodo.org/records/17167843/files/FANTASIA_UniProt_Sep2025_Last_ExpOnly.dump?download=1

  Explicitly use Final + intermediate layers (larger, more detailed)
  fantasia initialize --config ./fantasia/config.yaml \
    --embeddings_url https://zenodo.org/records/17151847/files/FANTASIA_UniProt_Sep2025_Final+Interm_ExpOnly.dump?download=1

So at the moment you need to provide the embeddings URL explicitly. You can do it in either of these two ways:

1. Pass it directly in the CLI with --embeddings_url
2. Uncomment one of the prepared embedding datasets in the YAML config

For example, in the YAML you should have something like:

# embeddings_url: "https://zenodo.org/records/17795871/files/BioData_Dec25_esm2_prott5_prostt5_ankh3_large_esm3c_Layer0.backup?download=1"
embeddings_url: "https://zenodo.org/records/17793273/files/BioData_Dec25_esm2_prott5_prostt5_ankh3_large_esm3c_Layers_3Frist_3Last.backup?download=1"

You can find these entries directly in the .yaml file.

So the issue is that, although the config comment says “leave empty to skip the preload step”, the current initialize code still expects the embeddings_url key to exist and raises a KeyError if it is missing entirely.

regards,
Francisco

[EricDeveaud]

gracias por la repuesta tan rapida ;-)

I saw the options, but as I'm lazy I edited the config.yaml to remove one #, not so difficult ;-)

regards

Eric