puppetlabs/puppet · error · InvalidFile

Could not find 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.

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 not found in environment .
• binary_file(): The given file
• Could not ' ';
• Could not find init script for '#
• Could not find init script or upstart conf file for '#

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

Appendix: 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)