Each entry starts from what you see, then explains the cause, how to confirm it, and how to fix it.
The entries apply to Cookieplone 2.0.
To change your answers after a generation, see Recover from mistakes.
Run Cookieplone
uvx cookieplone runs an older version
Symptom: uvx cookieplone --version shows an older version than you expect, or the questions differ from this documentation.
Cause: when you installed Cookieplone with uv tool install, uvx cookieplone runs the installed version.
An installed tool keeps its version until you upgrade it.
Diagnose: uv tool list shows the installed tools and their versions.
Fix: ask for the latest release, or pin a version:
For an installed tool, run uv tool upgrade cookieplone.
See Install Cookieplone.
"A valid repository for … could not be found"
Symptom: Cookieplone stops before the menu, with an error like this:
A valid repository for "/path/to/templates" could not be found in the following locations:
/path/to/templates
Cause: COOKIEPLONE_REPOSITORY points to a folder that doesn't exist, or that has no cookieplone-config.json at its root.
Diagnose: cookieplone --info shows the repository that Cookieplone uses.
Check that cookieplone-config.json exists at the root of that folder.
Fix: point COOKIEPLONE_REPOSITORY to the root of the template repository, or unset it to use cookieplone-templates.
Cookieplone can't clone the template repository
Symptom: Cookieplone stops before the menu with one of these errors, or waits a long time first:
Failed to clone '…'., followed by the output of git.
A message that ends with If this is a private repository, check your authentication.
Cannot clone '…': … Install the required VCS tool and retry.
Cause: Cookieplone can't clone the repository with git.
git may be missing, the network may block access to the repository, or the repository may not exist or may need authentication.
Diagnose: clone the repository yourself, in another folder:
git clone https://github.com/plone/cookieplone-templates.git
Fix: install git, or fix the network access that the clone needs.
To work around a network that blocks Cookieplone, clone the repository yourself, and set COOKIEPLONE_REPOSITORY to the clone.
The clone needs cookieplone-config.json at its root.
This repository requires cookieplone >= …
Symptom: Cookieplone stops with an error like this:
This repository requires cookieplone >= <required version>, but you have <installed version> installed.
Please upgrade: uvx --no-cache cookieplone@<required version>
Cause: the template repository sets config.min_version to a higher version than the Cookieplone you run.
Fix: run the command the message suggests.
For an installed tool, run uv tool upgrade cookieplone.
We do not have a template named …
Symptom: Cookieplone stops with this message:
We do not have a template named <template ID>.
Available templates are: <template IDs>
Exiting now.
Cause: the template ID you passed doesn't exist in the repository.
Fix: use one of the IDs that the message lists.
Official templates describes the templates of cookieplone-templates.
Config file … does not exist.
Symptom: Cookieplone stops with Config file <path> does not exist.
Cause: the file you passed with --answers-file doesn't exist.
Cookieplone reads a relative path from the current folder.
Fix: check the path to the answers file.
"Docker not found." with Docker installed
Symptom: the check results show Docker (optional): Docker not found., although Docker Desktop is installed.
Cause: the docker command isn't on your PATH.
On macOS, Docker Desktop can install it in ~/.docker/bin.
Diagnose: run docker --version.
Fix: add the folder with the docker command to your PATH.
The Docker check is a warning: generation continues without it.
"Output directory … already exists."
Symptom: Cookieplone stops after the questions with this message:
Output directory '<path>' already exists. Use --overwrite-if-exists or choose a different directory.
Cause: a folder with the name of the new project already exists in the output directory.
Fix: choose another output directory with -o, or remove the folder.
To generate into the existing folder, pass -f.
With -f, the hooks run again on the existing files; see Hooks and Update an existing project.
Default value '' for 'plone_version' fails validation
Symptom: a run with --no-input stops with this message:
Default value '' for 'plone_version' fails validation: is not a valid Plone version.
Cause: the default Plone version comes from PyPI.
Without network access, the lookup returns an empty value, which the validator rejects.
The default Volto version comes from the npm registry, and fails the same way.
Fix: restore network access, or pass the versions on the command line:
uvx cookieplone project plone_version=6.2.2 volto_version=19.4.1 --no-input
"Hook script failed"
Symptom: generation stops with a traceback and Hook script failed (exit status: <number>).
Cause: a pre_gen_project or post_gen_project hook of the template failed.
Cookieplone removes the new project folder.
Diagnose: read the output above the message.
To inspect the files generated so far, run again with --keep-project-on-failure.
Fix: fix the cause that the hook reports, such as a missing tool.
See Debug a failed generation.
make reports "No such file or directory" when the path has spaces
Symptom: while it generates a project, Cookieplone prints a make error that names only part of the path of your folder, and continues.
Cause: the path of the folder where you run Cookieplone contains spaces.
This issue is open: issue 208.
Fix: run Cookieplone in a folder whose path has no spaces.
ValueError: dictionary update sequence element #0 has length 3; 2 is required
Symptom: Cookieplone stops with this traceback when you pass key=value pairs.
Cause: a value contains =.
Fix: put that answer in an answers file.
See Set answers with extra context.
Develop templates
"No filter named '…'."
Symptom: generation stops with No filter named '<filter>'.
Cause: the template uses a Cookieplone filter that it doesn't declare.
Fix: add the filter, such as cookieplone.filters.pascal_case, to config.extensions in cookieplone.json.
See Use built-in filters.
"Cannot import validator module '…'"
Symptom: Cookieplone stops before the first question with Cannot import validator module '<module>': No module named '<module>'.
Cause: Python can't import the module that a validator key names.
Fix: put the module next to the template's cookieplone.json, or install its package with uvx --with.
See Add validators to your template.
"Reference at 'refs/heads/…' does not exist"
Symptom: generating from a local template repository fails with ValueError: Reference at 'refs/heads/<branch>' does not exist.
Cause: the repository is a git repository without any commit.
Fix: commit the files, or use the folder without git.
"Default value '…' for '…' fails validation"
Symptom: a run with --no-input stops with Default value '<value>' for '<field>' fails validation: <message>.
Cause: the default of a field, or a value you passed, fails the validator of that field.
With --no-input, nobody can type another answer.
Fix: change the default in cookieplone.json, or pass a valid value.
See Validator contract.
