{"record":{"id":"c5bbd647ff92af1f","repo":"puppetlabs/puppet","slug":"unable-to-find-metadata-json-in-module-root-at-p","errorCode":null,"errorMessage":"Unable to find metadata.json in module root at %{path} See https://puppet.com/docs/puppet/latest/modules_publishing.html for required file format.","messagePattern":"Unable to find metadata\\.json in module root at %(.+?) See https://puppet\\.com/docs/puppet/latest/modules_publishing\\.html for required file format\\.","errorType":"exception","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"lib/puppet/module_tool/applications/application.rb","lineNumber":50,"sourceCode":"            Puppet::Util::Json.load(response.body)['error']\n          rescue\n            \"HTTP #{response.code}, #{response.body}\"\n          end\n          Puppet.warning \"#{failure} (#{errors})\"\n        end\n      end\n\n      def metadata(require_metadata = false)\n        return @metadata if @metadata\n\n        @metadata = Puppet::ModuleTool::Metadata.new\n\n        unless @path\n          raise ArgumentError, _(\"Could not determine module path\")\n        end\n\n        if require_metadata && !Puppet::ModuleTool.is_module_root?(@path)\n          raise ArgumentError, _(\"Unable to find metadata.json in module root at %{path} See https://puppet.com/docs/puppet/latest/modules_publishing.html for required file format.\") % { path: @path }\n        end\n\n        metadata_path = File.join(@path, 'metadata.json')\n\n        if File.file?(metadata_path)\n          File.open(metadata_path) do |f|\n            @metadata.update(Puppet::Util::Json.load(f))\n          rescue Puppet::Util::Json::ParseError => ex\n            raise ArgumentError, _(\"Could not parse JSON %{metadata_path}\") % { metadata_path: metadata_path }, ex.backtrace\n          end\n        end\n\n        if File.file?(File.join(@path, 'Modulefile'))\n          Puppet.warning _(\"A Modulefile was found in the root directory of the module. This file will be ignored and can safely be removed.\")\n        end\n\n        @metadata\n      end","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/module_tool/applications/application.rb#L32-L68","documentation":"Application#metadata raises ArgumentError when require_metadata is true and Puppet::ModuleTool.is_module_root?(@path) is false — the directory does not contain a metadata.json at its root. Operations that fundamentally need module metadata (build, change-owner, unpack of an existing module) pass require_metadata = true (via load_metadata!), so a directory lacking metadata.json is rejected.","triggerScenarios":"Running `puppet module build` (or the Builder application) in a directory without metadata.json; passing a subdirectory of the module (manifests/, examples/) instead of the root; a module created from a bare skeleton that never got metadata.json.","commonSituations":"Old modules migrated from Modulefile-era layout that never got converted to metadata.json; running tooling from the wrong cwd; metadata.json accidentally renamed or gitignored; typos like metadata.json.bak.","solutions":["Run the command from the module's root directory — the one that should contain metadata.json.","Create a metadata.json with name, version, author, license, summary, source, dependencies (use `puppet module generate` as a template).","If metadata.json was renamed/removed, restore it from version control.","Remove the obsolete Modulefile if present (it is ignored and warned about)."],"exampleFix":"# before: module dir has only Modulefile\n\n# after: module root contains metadata.json\n{\n  \"name\": \"acme-webservice\",\n  \"version\": \"0.1.0\",\n  \"author\": \"acme\",\n  \"license\": \"Apache-2.0\",\n  \"summary\": \"Web service module\",\n  \"source\": \"https://github.com/acme/puppet-webservice\",\n  \"dependencies\": []\n}","handlingStrategy":"validation","validationCode":"require 'puppet/module_tool'\n\nabort 'not a module root: metadata.json missing' unless Puppet::ModuleTool.is_module_root?(path)","typeGuard":"def module_root?(path)\n  File.file?(File.join(path.to_s, 'metadata.json'))\nend","tryCatchPattern":"begin\n  app = Puppet::ModuleTool::Applications::Builder.new(path)\n  app.run\nrescue ArgumentError => e\n  raise unless e.message.include?('Unable to find metadata.json')\n  abort \"#{path} is not a module root - create metadata.json first\"\nend","preventionTips":["Bootstrap modules with `puppet module generate author-name` so metadata.json always exists.","Commit metadata.json and never gitignore it.","Guard scripts with Puppet::ModuleTool.is_module_root?(dir) before running module operations."],"tags":["puppet","module-tool","metadata-json","missing-file"],"backgroundTag":"missing-manifest-metadata","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}