{"record":{"id":"db56b34fbdb96cd0","repo":"apache/maven","slug":"error-while-deploying-metadata","errorCode":null,"errorMessage":"Error while deploying metadata: {}","messagePattern":"Error while deploying metadata: (.+?)","errorType":"exception","errorClass":"RepositoryMetadataDeploymentException","httpStatus":null,"severity":"error","filePath":"compat/maven-compat/src/main/java/org/apache/maven/artifact/repository/metadata/DefaultRepositoryMetadataManager.java","lineNumber":423,"sourceCode":"                }\n            }\n        } else {\n            // It's a POM - we don't need to retrieve it first\n            file = new File(\n                    localRepository.getBasedir(),\n                    localRepository.pathOfLocalRepositoryMetadata(metadata, deploymentRepository));\n        }\n\n        try {\n            metadata.storeInLocalRepository(localRepository, deploymentRepository);\n        } catch (RepositoryMetadataStoreException e) {\n            throw new RepositoryMetadataDeploymentException(\"Error installing metadata: \" + e.getMessage(), e);\n        }\n\n        try {\n            wagonManager.putArtifactMetadata(file, metadata, deploymentRepository);\n        } catch (TransferFailedException e) {\n            throw new RepositoryMetadataDeploymentException(\"Error while deploying metadata: \" + e.getMessage(), e);\n        }\n    }\n\n    @Override\n    public void install(ArtifactMetadata metadata, ArtifactRepository localRepository)\n            throws RepositoryMetadataInstallationException {\n        try {\n            metadata.storeInLocalRepository(localRepository, localRepository);\n        } catch (RepositoryMetadataStoreException e) {\n            throw new RepositoryMetadataInstallationException(\"Error installing metadata: \" + e.getMessage(), e);\n        }\n    }\n}\n","sourceCodeStart":405,"sourceCodeEnd":437,"githubUrl":"https://github.com/apache/maven/blob/e4093d4e120eac99d6bdce5ba67cace2f3085c97/compat/maven-compat/src/main/java/org/apache/maven/artifact/repository/metadata/DefaultRepositoryMetadataManager.java#L405-L437","documentation":"The final step of deploy() uploads the merged metadata file with wagonManager.putArtifactMetadata(...); a TransferFailedException there is rethrown as RepositoryMetadataDeploymentException with 'Error while deploying metadata' plus the transport message. This is a push-side failure against the deployment repository: most often authorization (401/403), a read-only or misconfigured repository, or a dropped connection during the PUT.","triggerScenarios":"mvn deploy reaching the metadata upload when the deploy user lacks write permission on the repository, credentials are wrong or missing, the target repository is a read-only mirror/group endpoint instead of a hosted repository, or the connection fails mid-upload.","commonSituations":"Deploying to a Nexus/Artifactory group or mirror URL instead of a hosted repository; CI credential rotation leaving stale tokens; disk quota exceeded on the repository manager; write policy of the hosted repo set to disable puts.","solutions":["Confirm the distributionManagement URL points at a hosted, deployable repository - not a mirror or group endpoint","Fix the settings.xml <server> credentials for the distributionManagement repository id","Check the repository manager logs for the failed PUT: permission denied, quota exceeded, or deployment policy blocking the upload","Retry the deploy after fixing; if a partial upload happened, remove the partial directory on the server and redeploy"],"exampleFix":"<!-- before: deploying into a group repository (read-only aggregate) -->\n<distributionManagement>\n  <repository><id>public</id><url>https://repo.example.com/repository/public/</url></repository>\n</distributionManagement>\n<!-- after: deploy to the hosted repository -->\n<distributionManagement>\n  <repository><id>releases-hosted</id><url>https://repo.example.com/repository/releases-hosted/</url></repository>\n</distributionManagement>","handlingStrategy":"try-catch","validationCode":"// probe deploy permission with a throwaway file before the real deploy\njava.net.HttpURLConnection c = (java.net.HttpURLConnection) new java.net.URL(\n        deployUrl + \"/.deploy-probe-\" + System.currentTimeMillis()).openConnection();\nc.setDoOutput(true);\nc.setRequestMethod(\"PUT\");\ntry (java.io.OutputStream os = c.getOutputStream()) { os.write(0); }\nint status = c.getResponseCode(); // 2xx = writable; 401/403 = fix credentials; 405 = read-only endpoint","typeGuard":null,"tryCatchPattern":"Catch RepositoryMetadataDeploymentException whose message starts with 'Error while deploying metadata'; read the cause TransferFailedException for the HTTP status; 401/403 -> credentials, 405/read-only -> wrong repository endpoint, IO -> network.","preventionTips":["Deploy only to hosted repositories with a permissive write policy; read via mirrors/groups.","Automate credential rotation so CI deploy tokens never go stale.","Monitor repository-manager disk quota and deployment policies."],"tags":["maven","deploy","metadata","upload","permissions","repository-manager"],"backgroundTag":"repository-upload-failed","analyzedSha":"e4093d4e120eac99d6bdce5ba67cace2f3085c97","analyzedAt":"2026-08-21T22:58:24.034Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}