What causes "File path has to be specified" in theonedev/onedev?

Append the target file path to the resource URL (e.g. .../index.html)

theonedev/onedev · error · ExplicitException

File path has to be specified

Error message

File path has to be specified

What it means

After validating segments, HtmlReportDownloadResource requires at least one non-empty path segment; otherwise it throws 'File path has to be specified'. The resource serves a specific file of the HTML report, so a request identifying only the report (no file) cannot be fulfilled.

Source

Thrown at server-plugin/server-plugin-report-html/src/main/java/io/onedev/server/plugin/report/html/HtmlReportDownloadResource.java:69

		String reportName = params.get(PARAM_REPORT).toString();
		if (reportName.contains(".."))
			throw new ExplicitException("Invalid request path");

		if (!SecurityUtils.canAccessReport(build, reportName))
			throw new UnauthorizedException();

		List<String> pathSegments = new ArrayList<>();

		for (int i = 0; i < params.getIndexedCount(); i++) {
			String pathSegment = params.get(i).toString();
			if (pathSegment.contains(".."))
				throw new ExplicitException("Invalid request path");
			if (pathSegment.length() != 0)
				pathSegments.add(pathSegment);
		}

		if (pathSegments.isEmpty())
			throw new ExplicitException("File path has to be specified");

		var filePath = Joiner.on("/").join(pathSegments);
		var fileName = filePath;
		if (fileName.contains("/"))
			fileName = StringUtils.substringAfterLast(fileName, "/");
		
		ResourceResponse response = new ResourceResponse();
		try {
			response.setContentType(Files.probeContentType(Paths.get(filePath)));
		} catch (IOException e) {
			throw new RuntimeException(e);
		}
		response.disableCaching();
		response.setFileName(URLEncoder.encode(fileName, UTF_8));
		
		response.setWriteCallback(new WriteCallback() {

			@Override

View on GitHub (pinned to d44925c47c)

Solutions

Append the target file path to the resource URL (e.g. .../index.html)
Point links at the report index page rather than the report root
Ensure the link template does not drop the file segment

Example fix

// before
GET /~resources/html-report/proj/12/report/
// after
GET /~resources/html-report/proj/12/report/index.html

Defensive patterns

Strategy: validation

Validate before calling

const filePath = segments.filter(Boolean).join('/');
if (!filePath) throw new Error('File path has to be specified');

Type guard

const hasFilePart = (parts) => Array.isArray(parts) && parts.filter(p => p && p.length).length > 0;

Try / catch

try { fetch(url); } catch (ExplicitException e) { // append default index.html and retry }

Prevention

Always append a concrete file (e.g. index.html) to report download URLs
Filter empty segments when composing URLs from variables
Default to the report entry page when no file is known

When it happens

Trigger: GET on the html report download resource where all indexed path params are empty or absent — the URL points at the report but not a file within it.

Common situations: Trailing-slash URLs with no file part; links generated to the report root instead of e.g. index.html; truncation of the URL by templates.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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