The template was not applied and said nothing: diagnostics

Updated 5 November 2026

The most common question is "I created a template, ran the setup, and the file is not there". Templates almost never "fail silently": they simply do not get into the selection. Below are the causes in decreasing order of frequency, each with a check.

1. Wrong event directory name

The first-level directory must have a header with an action variable - in the .calculate_directory file, for example # Calculate append=skip env=install ac_install_merge==on. The directory itself can be named anything: the merge does not distinguish merge, xyz or 2_ac_install_merge, the utilities do not look for "similar names" and do not guess anything. Without an action variable the subtree is not applied - the verbose output will show Skipped directories:. The N_ac_[HTML_REMOVED] convention is needed for something else: directories are traversed in lexicographic order, so the number at the start of the name sets the merge order.

Check: compare with the actual set in /var/db/repos/calculate/profiles/templates/ (see the event map).

2. No action variable on the first-level directory or file

For the user layer (/var/calculate/templates) the rule is strict: every first-level element - both directory and file - must have in its header an action variable (ac_*) or cl_name==. If it is missing, the subtree is skipped and the setup process is marked as failed; in the verbose output you will see the "Skipped templates:" listing and a hint about a header of the form # Calculate ac_install_merge==on.

Trees in repositories (/var/db/repos/…) are excluded from this rule - there env= and the action are set at the event directory level.

Binary files are not allowed at the first level in any case.

3. Required action condition not specified

Classic case: the template sits in the right directory, but the header lacks env=install ac_install_merge==on - or vice versa, it carries the condition ac_desktop_profile==on, while you run package setup.

Check the values of the variables for that run:

Action variables live in the install module, so without the prefix, cl-variable does not find them and replies Variable not found. An empty line in the reply means the variable is defined but has no value (for example, cl_merge_pkg outside package setup).

4. Template bound to a package that is not being configured now

The conditions mergepkg(<category>/<package>)!=, merge(...)!=, pkg(...)!= are package filters. They are true if the package is being configured now or is listed in the setup cache:

/var/lib/calculate/calculate-core/cache/merge-setup.list   # package setup
/var/lib/calculate/calculate-core/cache/merge-patch.list   # patches

Two non-obvious consequences follow. The first: a template bound to an uninstalled package will never be applied - it will take effect on the first installation of that package. The second: mergepkg() with no arguments takes the package category and name from the path ([HTML_REMOVED]/[HTML_REMOVED]/…), so a wrongly named package directory gives a quietly non-working template.

You can check the package names in these conditions in advance, without running the merge: cl-check-templates (the sys-apps/calculate-toolkit package, installed as /usr/sbin/cl-check-templates) parses the pkg() and merge() conditions - and with them mergepkg() - and matches the named packages against the repositories and the installed package database, taking renames into account. A typo in a package name is not "the template did not match" but "it will never match".

Check: run the setup of this very package and look at the verbose output:

It lists the applied templates and the errors for each file.

5. No available variables module specified

The env=[HTML_REMOVED] parameter pulls in the variables of the corresponding utilities package. If the module is not in the system, the template is skipped without an error message. The symptom: in cl-variable the variable is undefined. The same applies to conditions on ini(...): they read the ini.env stack, and if the needed section is in no layer, the condition is false. Many "switchable" templates in overlays are built exactly this way: they are marked as disabled and wait for the administrator to enable them with a value in ini.env.

6. Error in the template itself

• incorrect header parameter: '<name>' - the header parameter does not exist for a file or a directory (recall: the set of parameters for a directory is noticeably shorter);
• function of templates '<name>' not found - the header or body uses a function that is neither built-in nor an overlay function: the template is aborted;
• Failed to apply custom function … - a function from scripts/functions returned an error: the substitution becomes empty, the template is applied, but "in the wrong place";
• Wrong option 'append=<value>' in template <file> - for patch and the "executable" formats (diff, dconf, contents, sqlite, backgrounds) the merge method must be patch;
• Wrong value '<x>' in the template - an incorrect parameter value (for example, a relative path=).

Previewing what the template will create

Without waiting for the real system setup, you can direct the results to a directory: --pkg-path sets the root path for the saved configuration files.

* System configuring for baselayout package by Calculate Utilities ...
 * Calculate Utilities have changed files:
 *      /tmp/clt-preview/etc/profile.d/editor.sh
 *      /tmp/clt-preview/etc/os-release

The real files are not changed by this - check ls -l /etc/profile.d/editor.sh. This is a convenient way to see exactly what will come out of your template, including the control record and the layout across directories.

It is also useful to make sure that the template creates no extra directories: by comparing the find /tmp/clt-preview output with expectations. A template directory without .calculate_directory appears in the result as a real directory - if it must not be there, add # Calculate append=skip. A first-level directory in /var/calculate/templates carries one more requirement: its header must contain an action variable, otherwise the entire subtree is skipped without a message (in the verbose output - Skipped directories:).

What to do if nothing helped

1. --pkg-path + -v: if you see the file in the result, the problem is not in the template but in the selection (items 1-5).
2. Remove all conditions from the header except env=install ac_install_merge==on and check again: if it works now, one of the removed conditions is "to blame" - restore them one by one.

3. Compare with a working analogue: the calculate tree has a ready template for almost any package; search like this:

   grep -rl 'format=kde' /var/db/repos/calculate/profiles/templates | head

See also

• Who and when merges templates
• Template variables
• Template syntax