theonedev/onedev · error · ExplicitException

Field not found: ${fieldName}

Error message

Field not found: ${fieldName}

What it means

BuildMetricQuery.checkField validates that a field name used in a build-metric query criterion is either one of the built-in metric query fields (job name, branch, report, pull request, etc.) or a build parameter name registered with BuildParamService for the project. If the name matches neither list, an ExplicitException with 'Field not found: <fieldName>' is thrown. This guards saved query/criteria definitions against typos and stale field references.

Source

Thrown at server-core/src/main/java/io/onedev/server/search/buildmetric/BuildMetricQuery.java:166

					public BuildMetricCriteria visitNotCriteria(NotCriteriaContext ctx) {
						return new NotBuildMetricCriteria(visit(ctx.criteria()));
					}

				}.visit(criteriaContext);
			} else {
				metricCriteria = null;
			}

			return new BuildMetricQuery(metricCriteria);
		} else {
			return new BuildMetricQuery();
		}
	}
	
	public static void checkField(Project project, String fieldName, int operator) {
		Collection<String> paramNames = OneDev.getInstance(BuildParamService.class).getParamNames(null);
		if (!METRIC_QUERY_FIELDS.contains(fieldName) && !paramNames.contains(fieldName)) 
			throw new ExplicitException("Field not found: " + fieldName);
		switch (operator) {
			case Is:
			case IsNot:
				if (!fieldName.equals(NAME_JOB) && !fieldName.equals(NAME_BRANCH)
						&& !fieldName.equals(BuildMetric.NAME_REPORT)
						&& !paramNames.contains(fieldName)) {
					throw newOperatorException(fieldName, operator);
				}
				break;
			case IsEmpty:
			case IsNotEmpty:
				if (!fieldName.equals(NAME_PULL_REQUEST) && !paramNames.contains(fieldName))
					throw newOperatorException(fieldName, operator);
				break;
		}
	}
	
	private static ExplicitException newOperatorException(String fieldName, int operator) {

View on GitHub (pinned to d44925c47c)

Solutions

1. Fix the field name to one of the supported metric query fields or an existing build parameter (check the project's build parameter list).
2. If the field was a build parameter, re-create the parameter in the project's build configuration or update the saved query to drop it.
3. Catch ExplicitException at the call site to surface a friendly message to the end user instead of a stack trace.

Example fix

// before
BuildMetricQuery.checkField(project, "jobname", operator);
// after
BuildMetricQuery.checkField(project, BuildMetricQuery.NAME_JOB, operator);

Set<String> valid = new HashSet<>(BuildMetricQuery.METRIC_QUERY_FIELDS);
valid.addAll(OneDev.getInstance(BuildParamService.class).getParamNames(null));
if (!valid.contains(fieldName)) throw new IllegalArgumentException("Unknown field: " + fieldName);

boolean isValidMetricField(String f, Project p) {
    return BuildMetricQuery.METRIC_QUERY_FIELDS.contains(f)
        || OneDev.getInstance(BuildParamService.class).getParamNames(null).contains(f);
}

try {
    BuildMetricQuery.checkField(project, fieldName, operator);
} catch (ExplicitException e) {
    throw new UserFriendlyException(e.getMessage());
}

When it happens

Trigger: Calling BuildMetricQuery.checkField(project, fieldName, operator) — directly or via visitFieldOperatorCriteria/visitFieldOperatorValueCriteria during query parsing — with a fieldName that is neither in METRIC_QUERY_FIELDS nor in the project's build parameter names (e.g. a typo like 'jobname' instead of 'Job Name', or a parameter that was deleted).

Common situations: Typing a wrong field name in a metric query in the UI or REST call; renaming or deleting a build parameter that a saved metric query still references; writing custom code that constructs build metric criteria with an invalid field.

Understand the failure class

Background: "Invalid query parameter" / "Failed to parse value of ...": fixing bad query string parameters across APIs — this error's family across 36 libraries.

Related errors

• Malformed query
• Unexpected operator: ${operatorText}
• Criteria '${operator}' is not supported here
• Unexpected operator: ${operator}
• Unexpected criteria: ${operator}

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