ansible/ansible · error · AnsibleOptionsError

URL for repository not specified, use -h for help

Error message

URL for repository not specified, use -h for help

What it means

`ansible-pull` clones a repository before running its playbook, so a source URL is mandatory. `post_process_args` raises `AnsibleOptionsError` when `options.url` (from `-U/--url`) is empty — there is no default and no way to proceed.

Source

Thrown at lib/ansible/cli/pull.py:179

        options = super(PullCLI, self).post_process_args(options)

        if not options.dest:
            hostname = socket.getfqdn()
            # use a hostname dependent directory, in case of $HOME on nfs
            options.dest = os.path.join(C.ANSIBLE_HOME, 'pull', hostname)

        if os.path.exists(options.dest) and not os.path.isdir(options.dest):
            raise AnsibleOptionsError("%s is not a valid or accessible directory." % options.dest)

        if options.sleep:
            try:
                secs = secrets.randbelow(int(options.sleep))
                options.sleep = secs
            except ValueError:
                raise AnsibleOptionsError("%s is not a number." % options.sleep)

        if not options.url:
            raise AnsibleOptionsError("URL for repository not specified, use -h for help")

        if options.module_name not in self.REPO_CHOICES:
            raise AnsibleOptionsError("Unsupported repo module %s, choices are %s" % (options.module_name, ','.join(self.REPO_CHOICES)))

        display.verbosity = options.verbosity
        self.validate_conflicts(options)

        return options

    def run(self):
        """ use Runner lib to do SSH things """

        super(PullCLI, self).run()

        # log command line
        now = datetime.datetime.now()
        display.display(now.strftime("Starting Ansible Pull at %F %T"))
        display.display(' '.join(sys.argv))

View on GitHub (pinned to 9cf16a4aca)

Solutions

1. Supply the repo URL: `ansible-pull -U https://github.com/org/repo.git ...`.
2. Check the systemd unit / cron script for empty variables (`set -u`, `EnvironmentFile`) and add a guard before invoking ansible-pull.
3. Run `ansible-pull -h` to confirm the exact option spelling being used.

Example fix

# before
ansible-pull -i localhost,

# after
ansible-pull -U https://github.com/org/repo.git -i localhost,

url = os.environ.get('PULL_URL')
assert url, 'PULL_URL must be set (ansible-pull -U)'
run(['ansible-pull', '-U', url])

When it happens

Trigger: Running `ansible-pull` with no `-U` at all; passing `-U` with an empty value (`-U ""`) from an unset variable in a systemd unit or cron line.

Common situations: Templated systemd units/cron jobs where the URL environment variable is not exported; shell quoting mistakes that swallow the value; typos using `--url` long form with `=` and nothing after.

Related errors

• %s is not a valid or accessible directory.
• %s is not a number.
• Unsupported repo module %s, choices are %s
• - you must specify at least one role to remove.
• Invalid query. At least one search term, platform, galaxy ta

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