puppetlabs/puppet · error · InvalidFile

Could not find %{path} on disk

Error message

Could not find %{path} on disk

What it means

Raised by Puppet::Module::Task#get_file_details when a file path listed in a task's metadata.json 'files' array resolves (relative to the module root plus its mount point) to a path that does not exist on disk. The task metadata declares supporting files that get bundled with the task; if the declaration points at a missing file, the task cannot be packaged or executed. This is a Puppet::Module::Task::InvalidFile error.

Source

Thrown at lib/puppet/module/task.rb:133

                  { module_name: module_name, filename: endpath })
          raise InvalidMetadata.new(msg, 'puppet.tasks/invalid-metadata')
        end

        unless MOUNTS.include? mount
          msg = _("Files must be saved in module directories that Puppet makes available via mount points: %{mounts}" %
                  { mounts: MOUNTS.join(', ') })
          raise InvalidMetadata.new(msg, 'puppet.tasks/invalid-metadata')
        end

        path = File.join(pup_module.path, mount, endpath)
        unless File.absolute_path(path) == File.path(path).chomp('/')
          msg = _("File pathnames cannot include relative paths")
          raise InvalidMetadata.new(msg, 'puppet.tasks/invalid-metadata')
        end

        unless File.exist?(path)
          msg = _("Could not find %{path} on disk" % { path: path })
          raise InvalidFile, msg
        end

        last_char = file[-1] == '/'
        if File.directory?(path)
          unless last_char
            msg = _("Directories specified in task metadata must include a trailing slash: %{dir}" % { dir: file })
            raise InvalidMetadata.new(msg, 'puppet.tasks/invalid-metadata')
          end
          dir_files = Dir.glob("#{path}**/*").select { |f| File.file?(f) }
          dir_files.map { |f| get_file_details(f, pup_module) }
        else
          if last_char
            msg = _("Files specified in task metadata cannot include a trailing slash: %{file}" % { file: file })
            raise InvalidMetadata.new(msg, 'puppet.task/invalid-metadata')
          end
          get_file_details(path, pup_module)
        end
      end

View on GitHub (pinned to e227c27540)

Solutions

1. Verify each entry in the task metadata.json 'files' array exists under the module root, creating the missing file.
2. Fix path typos, wrong mount point ('files/' vs 'tasks/'), or case mismatches in the metadata strings.
3. Remove stale 'files' entries for files that no longer ship with the task.
4. Re-run `puppet module build` or the task listing command to confirm resolution succeeds.

Example fix

// tasks/mytask.json - before
{ "implementations": [{ "name": "mytask.py" }], "files": ["files/helper.sh"] }

// after (helper removed or restored)
{ "implementations": [{ "name": "mytask.py" }], "files": [] }

meta = Puppet::Util::Json.load(File.read(task_metadata_path))
files = meta.fetch('files', [])
missing = files.reject { |f| File.exist?(File.join(module_root, f.chomp('/'))) }
abort "metadata references missing files: #{missing}" unless missing.empty?

begin
  Puppet::Module::Task.instances(mod)
rescue Puppet::Module::Task::InvalidFile => e
  warn "task file missing: #{e.message}" # skip this task, continue
end

When it happens

Trigger: metadata.json for a task contains a 'files' entry like "files/foo.sh" but that file was never created, was renamed, or was not committed to the module repo; running `puppet app show` / `bolt task show` / task packaging invokes Task.get_file_details which does File.exist?(File.join(module.path, mount, endpath)) and raises when it returns false.

Common situations: Task file listed in metadata but .gitignore'd (e.g. compiled binaries); case-sensitivity mismatch between metadata ('Files/plans.rb') and filesystem after developing on macOS/Windows and deploying to Linux; moving a helper script without updating metadata.json; packaging a module on a machine where the file was deleted.

Related errors

• Module %{module_name} not found in environment %{environment
• Could not %{action} '%{module_name}'; %{error}
• One or more file(s) specified did not exist: %{files}
• File not found
• Fileset paths must exist

AI-assisted analysis of puppetlabs/puppet@e227c27540 (2026-08-21). Data as JSON: /api/errors/dd932055c2fcb531. Report an issue: GitHub.