ansible/ansible · error · ArgumentException

argument spec entry contains an invalid key '{0}', valid key

Error message

argument spec entry contains an invalid key '{0}', valid keys: {1}

What it means

Raised by git's set_git_dir/worktree handling when separating the .git directory from a worktree: shutil.move of the repo dir into place plus writing the 'gitdir: ' pointer file raised OSError. The code attempts rollback (moving the dir back) and chains the original OSError behind a generic Exception.

Source

Thrown at lib/ansible/module_utils/csharp/Ansible.Basic.cs:720

            NTAccount account = new NTAccount(stringValue);
            return (SecurityIdentifier)account.Translate(typeof(SecurityIdentifier));
        }

        public static string ParseStr(object value) { return value.ToString(); }

        private void ValidateArgumentSpec(IDictionary argumentSpec)
        {
            Dictionary<string, object> changedValues = new Dictionary<string, object>();
            foreach (DictionaryEntry entry in argumentSpec)
            {
                string key = (string)entry.Key;

                // validate the key is a valid argument spec key
                if (!specDefaults.ContainsKey(key))
                {
                    string msg = String.Format("argument spec entry contains an invalid key '{0}', valid keys: {1}",
                        key, String.Join(", ", specDefaults.Keys));
                    throw new ArgumentException(FormatOptionsContext(msg, " - "));
                }

                // ensure the value is casted to the type we expect
                Type optionType = null;
                if (entry.Value != null)
                    optionType = (Type)specDefaults[key][1];
                if (optionType != null)
                {
                    Type actualType = entry.Value.GetType();
                    bool invalid = false;
                    if (optionType.IsGenericType && optionType.GetGenericTypeDefinition() == typeof(List<>))
                    {
                        // verify the actual type is not just a single value of the list type
                        Type entryType = optionType.GetGenericArguments()[0];
                        object[] arrayElementTypes = new object[]
                        {
                            null,  // ArrayList does not have an ElementType
                            entryType,

View on GitHub (pinned to 9cf16a4aca)

Solutions

Inspect and clean both locations on the target: the worktree .git pointer and the separate_git_dir path; remove partial leftovers
Ensure the separate_git_dir destination is on a writable filesystem with space and is not already a populated dir
Re-run the task after cleanup — the clone is re-attempted from scratch

Example fix

# before
- ansible.builtin.git:
    repo: https://example.com/r.git
    dest: /srv/work
    separate_git_dir: /srv/gitstore/r.git
# after (clean partial state first)
- ansible.builtin.file:
    path: '{{ item }}'
    state: absent
  loop: [/srv/work, /srv/gitstore/r.git]
- ansible.builtin.git:
    repo: https://example.com/r.git
    dest: /srv/work
    separate_git_dir: /srv/gitstore/r.git

Defensive patterns

Strategy: try-catch

Validate before calling

import os
if os.path.exists(separate_git_dir) and os.listdir(separate_git_dir):
    raise RuntimeError(f'{separate_git_dir} already populated; clean before separate_git_dir clone')

Try / catch

try:
    set_git_dir(dest, repo_dir, worktree_dir)
except Exception as e:
    module.fail_json(msg=str(e), cause=repr(e.__cause__))

Prevention

Clean dest and separate_git_dir paths before re-running failed worktree clones
Keep the separate git dir on the same filesystem as the worktree to avoid cross-device renames

When it happens

Trigger: Cloning with separate_git_dir: /path while a leftover directory already exists at the target of the move, the destination filesystem is read-only/full, or the worktree dir is not writable. The rollback itself can also fail, leaving partial state.

Common situations: Re-running a failed separate_git_dir task where /path/.git or the target repo dir already exists; NFS or container volumes refusing renames across filesystems; insufficient privileges on the clone destination.

Related errors

AI-assisted analysis of ansible/ansible@9cf16a4aca (2026-08-15). Data as JSON: /api/errors/df7d0c27a69281e6. Report an issue: GitHub.