theonedev/onedev · error · ClientException

Tag body exceeds maximum size:

Error message

Tag body exceeds maximum size: 

What it means

When publishing/updating npm dist-tags via PUT, the handler buffers the request body up to MAX_TAG_BODY_LEN using copyWithMaxSize. If the body exceeds that limit (copy returns -1), it rejects the request with HTTP 406 Not Acceptable 'Tag body exceeds maximum size: <limit>'.

Source

Thrown at server-plugin/server-plugin-pack-npm/src/main/java/io/onedev/server/plugin/pack/npm/NpmPackHandler.java:195

									} catch (IOException e) {
										throw new RuntimeException(e);
									}
								});
							} else {
								throw new ClientException(SC_METHOD_NOT_ALLOWED);
							}
						} else {
							sessionService.run(() -> {
								checkProject(projectId, true);
							});
							var tag = decodePath(pathSegments.get(2));
							LockUtils.run(getLockName(projectId, packageName), () -> {
								if (isPut) {
									var baos = new ByteArrayOutputStream();
									try (var is = request.getInputStream()) {
										var copied = copyWithMaxSize(is, baos, MAX_TAG_BODY_LEN);
										if (copied == -1)
											throw new ClientException(SC_NOT_ACCEPTABLE, "Tag body exceeds maximum size: " + MAX_TAG_BODY_LEN);
									} catch (IOException e) {
										throw new RuntimeException(e);
									}
									var version = StringUtils.strip(baos.toString(UTF_8), "\"");
									transactionService.run(() -> {
										var project = projectService.load(projectId);
										var pack = packService.findByNameAndVersion(project, TYPE, packageName, version);
										if (pack != null) {
											var packData = (NpmData) pack.getData();
											packData.getDistTags().add(tag);
										} else {
											throw new ClientException(SC_NOT_FOUND);
										}
									});
									response.setStatus(SC_OK);
								} else if (isDelete) {
									transactionService.run(() -> {
										var project = projectService.load(projectId);

View on GitHub (pinned to d44925c47c)

Solutions

1. Ensure the PUT dist-tag body is only the version string (e.g. "1.2.3")
2. Check client code/CI scripts for accidentally posting metadata or tarballs to the dist-tags endpoint
3. If a legitimate larger body is needed, raise MAX_TAG_BODY_LEN in NpmPackHandler or use the npm publish flow instead

Example fix

// before
await fetch(`${registry}/-/package/${name}/dist-tags/latest`, {method:'PUT', body: JSON.stringify(fullMetadata)})
// after
await fetch(`${registry}/-/package/${name}/dist-tags/latest`, {method:'PUT', body: '"1.2.3"'})

const body = '"1.2.3"';
if (body.length > 128) throw new Error('dist-tag body must be a short quoted version string');

try { await putDistTag(url, body) } catch (e) { if (e.response?.status === 406 && /Tag body exceeds maximum size/i.test(e.message ?? '')) { console.error('Dist-tag PUT body too large — send only the version string'); } else throw e }

When it happens

Trigger: PUT to the /-/package/<name>/dist-tags route with a body larger than MAX_TAG_BODY_LEN — the body should be a short quoted version string, so this happens when the client sends a large payload instead.

Common situations: Misconfigured clients that send full package metadata to the dist-tag endpoint; pipelined/multiplexed uploads posting the wrong body to the tag route; custom scripts posting JSON documents as a tag.

Understand the failure class

Background: "File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them — this error's family across 46 libraries.

Related errors

• Package metadata exceeds maximum size:
• Package management not enabled for project ''
• ${e.getMessage()}
• An active subscription is required for this feature
• Time tracking needs to be enabled for the project

AI-assisted analysis of theonedev/onedev@d44925c47c (2026-09-06). Data as JSON: /api/errors/8da4a51a3e5e06d6. Report an issue: GitHub.