theonedev/onedev · error · TooGeneralQueryException

Text query is too general: ${term}

Error message

Text query is too general: ${term}

What it means

TextQueryOption.applyConstraints builds a Lucene n-gram query over blob text for code text search. Non-regex terms shorter than the index's NGRAM_SIZE cannot be represented in the n-gram index, so instead of silently returning no results, TooGeneralQueryException is thrown when term.length() < NGRAM_SIZE.

Source

Thrown at server-core/src/main/java/io/onedev/server/search/code/query/TextQueryOption.java:209

	public void applyConstraints(BooleanQuery.Builder builder) {
		Preconditions.checkNotNull(term);
		
		if (fileNames != null) {
			BooleanQuery.Builder subQueryBuilder = new BooleanQuery.Builder();
			for (String pattern: Splitter.on(",").omitEmptyStrings().trimResults().split(fileNames.toLowerCase()))
				subQueryBuilder.add(new WildcardQuery(new Term(BLOB_NAME.name(), pattern)), BooleanClause.Occur.SHOULD);
			BooleanQuery subQuery = subQueryBuilder.build();
			if (subQuery.clauses().size() != 0)
				builder.add(subQuery, BooleanClause.Occur.MUST);
		}

		if (regex)
			builder.add(new RegexLiterals(term).asNGramQuery(BLOB_TEXT.name(), NGRAM_SIZE), BooleanClause.Occur.MUST);
		else if (term.length() >= NGRAM_SIZE)
			builder.add(new NGramLuceneQuery(BLOB_TEXT.name(), term, NGRAM_SIZE), BooleanClause.Occur.MUST);
		else
			throw new TooGeneralQueryException("Text query is too general: " + term);
	}

	@Override
	public FormComponentPanel<? extends QueryOption> newOptionEditor(String componentId) {
		return new TextQueryOptionEditor(componentId, Model.of(this));
	}

	public static class Match implements Serializable {

		private static final long serialVersionUID = 1L;
		
		private final String line;
		
		private final PlanarRange position;
		
		public Match(String line, PlanarRange position) {
			this.line = line;
			this.position = position;

View on GitHub (pinned to d44925c47c)

Solutions

1. Search for a term at least NGRAM_SIZE characters long, or use the regex option (regex=true) which extracts literals from the pattern.
2. Extend the search term with more context, e.g. 'if(' or surrounding identifier characters.
3. Catch TooGeneralQueryException in the search entry point and inform the user of the minimum term length.

Example fix

// before
new TextQuery().withOption(new TextQueryOption("if", false, false, true));
// after
new TextQuery().withOption(new TextQueryOption("if(", false, false, true));

if (!regex && term.length() < 3) // NGRAM_SIZE
    throw new IllegalArgumentException("Text term must be at least 3 characters (or use regex)");

boolean isUsableTextTerm(String term, boolean regex, int ngramSize) {
    return regex || (term != null && term.length() >= ngramSize);
}

try {
    query = new TextQuery().withOption(new TextQueryOption(term, regex, false, true));
} catch (TooGeneralQueryException e) {
    return Result.error("Term too short for text search: " + term);
}

When it happens

Trigger: Creating a TextQuery with a non-regex term shorter than NGRAM_SIZE (typically 3 characters, e.g. 'ab') and applying its constraints during code text search; also via the code search UI with a very short keyword.

Common situations: User searches for a 1-2 character string like 'if' or 'x' in code search; programmatic text search passing short user input; misunderstanding that short substrings are not indexed.

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

• File query is too general: ${term}
• Symbol query is too general: ${term}
• Regex query is too general: ${regex}

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