Troubleshooting

Troubleshooting#

"I made a mistake answering a question"#

Cookieplone saves your answers to .cookieplone.json in the generated project directory. You have two options:

  1. Edit .cookieplone.json to fix the incorrect value, then re-run:

    cookieplone --answers-file /path/to/.cookieplone.json

  2. Delete the generated directory and run cookieplone again from scratch.

See Recover from mistakes for a detailed walkthrough.

"X is not a valid Plone version"#

Cookieplone checks that the Plone version is at least 6.0. Common causes:

  • Typing 5.2: Plone 5.x is not supported.

  • Typing latest: enter an actual version number such as 6.1.1.

  • Network error—version validation requires internet access to check the latest release. Verify your connection and try again.

"A valid repository could not be found"#

This error usually means one of the following:

  • No internet connection—Cookieplone downloads templates from GitHub.

  • GitHub is unavailable or rate-limiting requests.

  • A custom COOKIEPLONE_REPOSITORY is set to an invalid URL.

Run with --verbose for detailed logs:

cookieplone --verbose

See Environment variables reference for details on COOKIEPLONE_REPOSITORY.

"Hook script failed"#

Template hooks run Python scripts before and after generation. If a hook fails:

  • Check the error output above the Cookieplone error message.

  • Common cause: missing system dependencies such as git, docker, or node.

  • Use --keep-project-on-failure to inspect the partial output:

    cookieplone --keep-project-on-failure

See Debug a failed generation for a full debugging workflow.

"Output directory already exists"#

This error occurs when the target directory already exists and --overwrite-if-exists was not passed. You have two options:

  1. Pass -f (--overwrite-if-exists) to merge new output over the existing directory:

    cookieplone -f

  2. Choose a different output directory with -o:

    cookieplone -o ~/projects/new-location

"File exists error when re-running with -f"#

Re-running Cookieplone with -f (--overwrite-if-exists) on an existing project merges the new output over the existing directory. If you see a FileExistsError, check that you are using Cookieplone 1.0.0 or later, which contains the fix for issue #139.

No module named cookieplone#

If you installed Cookieplone with pip rather than uvx, ensure the virtual environment is activated and that the installation completed without errors. The recommended installation method is uvx:

uvx cookieplone

Still stuck#

Open an issue at plone/Cookieplone#issues with the output of:

cookieplone --info
cookieplone --verbose 2>&1 | head -50
Contents