NationalSecurityAgency/ghidra · error · QueryDatabaseException

Connection to database not established

Error message

Connection to database not established

What it means

Thrown by SimilarFunctionQueryService.overviewSimilarFunctions when the database handle is null or its Status is not Status.Ready. The overview path mirrors querySimilarFunctions' connection guard (note slightly different wording: 'Connection to database not established' vs 'with database'). Only Status.Ready permits the overview query to proceed.

Source

Thrown at Ghidra/Features/BSim/src/main/java/ghidra/features/bsim/query/facade/SimilarFunctionQueryService.java:200

	}

	/**
	 * Query the given server for similar function overview information
	 * @param overviewInfo is details of the overview query
	 * @param listener is the listener to be informed of the query status and incremental results 
	 * 		coming back, may be null
	 * @param monitor the task monitor
	 * @return the ResponseNearestVector
	 * @throws QueryDatabaseException if the database connection cannot be established
	 * @throws CancelledException if the query is cancelled by the user
	 */
	public ResponseNearestVector overviewSimilarFunctions(SFOverviewInfo overviewInfo,
			SFResultsUpdateListener<ResponseNearestVector> listener, TaskMonitor monitor)
			throws QueryDatabaseException, CancelledException {
		ResponseNearestVector response = null;
		try {
			if (database == null || database.getStatus() != Status.Ready) {
				throw new QueryDatabaseException("Connection to database not established");
			}
			if (monitor == null) {
				monitor = TaskMonitor.DUMMY;
			}
			if (listener == null) {
				listener = new NullListener<>();
			}

			QueryNearestVector query = generateQueryNearestVector(overviewInfo, monitor);
			int localNumStages = numStages;
			if (localNumStages == 0) {
				int funcsPerStage = database.getOverviewFunctionsPerStage();
				localNumStages = overviewInfo.getNumberOfStages(funcsPerStage);
			}
			StagingManager stagingManager =
				createStagingManager(overviewInfo.getFunctions().size(), localNumStages);

			try {

View on GitHub (pinned to d5f144c24d)

Solutions

1. Connect/initialize the service so database.getStatus()==Ready before calling overviewSimilarFunctions.
2. Do not call after dispose(); create a new service instance instead.
3. On Error, inspect getLastError(), re-establish connection, then retry.
4. Avoid concurrent calls on one service instance.

Example fix

// before
ResponseNearestVector v = service.overviewSimilarFunctions(overviewInfo, listener, monitor);
// after
if (service.getStatus() != Status.Ready) {
    throw new IllegalStateException("BSim DB not ready");
}
ResponseNearestVector v = service.overviewSimilarFunctions(overviewInfo, listener, monitor);

if (service.getStatus() != Status.Ready) {
    throw new IllegalStateException("BSim DB not ready");
}
ResponseNearestVector v = service.overviewSimilarFunctions(overviewInfo, listener, monitor);

static boolean isReady(FunctionDatabase db) {
    return db != null && db.getStatus() == Status.Ready;
}

try {
    service.overviewSimilarFunctions(overviewInfo, listener, monitor);
} catch (QueryDatabaseException e) {
    if (e.getMessage().contains("not established")) { /* reconnect, retry */ }
}

When it happens

Trigger: Invoking overviewSimilarFunctions before connecting, after dispose(), or while the database is Busy/Error/Unconnected.

Common situations: Service not initialized before overview call; reused after close; prior query left Error state; concurrent access marking Busy.

Related errors

• Connection with database not established
• Function list cannot be null
• Function list cannot be empty
• all function symbols are not from the same program
• Unable to connect to server

AI-assisted analysis of NationalSecurityAgency/ghidra@d5f144c24d (2026-08-14). Data as JSON: /api/errors/fdc80ae2d39b73fb. Report an issue: GitHub.