NationalSecurityAgency/ghidra · error · QueryDatabaseException

Connection with database not established

Error message

Connection with database not established

What it means

Thrown by SimilarFunctionQueryService.querySimilarFunctions when the internal database handle is null or its Status is not Status.Ready. The Status enum is Unconnected/Busy/Error/Ready; only Ready means the connection is established and idle enough to query. Querying in any other state is rejected before any signatures are generated.

Source

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

	/**
	 * Query the given server with the parameters provider by {@code queryInfo}.
	 * 
	 * @param queryInfo a query info object containing the settings for the 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 to use; can be null
	 * @return the result object containing the retrieved similar functions; null if the query
	 *         was cancelled
	 * @throws QueryDatabaseException if the query execution fails
	 * @throws CancelledException if the query is cancelled by the user
	 */
	public SFQueryResult querySimilarFunctions(SFQueryInfo queryInfo,
			SFResultsUpdateListener<SFQueryResult> listener, TaskMonitor monitor)
			throws QueryDatabaseException, CancelledException {
		SFQueryResult result = null;
		try {
			if (database == null || database.getStatus() != Status.Ready) {
				throw new QueryDatabaseException("Connection with database not established");
			}
			if (monitor == null) {
				monitor = TaskMonitor.DUMMY;
			}
			if (listener == null) {
				listener = new NullListener<>();
			}

			//
			// Perform the required initialization:
			// -Initialize signature generator
			// -Hash the functions
			// -Create the query
			// -Create the staging
			//

			QueryNearest query = generateQueryNearest(queryInfo, monitor);
			int localNumStages = numStages;

View on GitHub (pinned to d5f144c24d)

Solutions

1. Ensure SimilarFunctionQueryService is connected (database != null and getStatus()==Ready) before invoking; call your connect/initialize path first.
2. Do not call any query method after dispose()/close(); obtain a fresh service instance.
3. If Status is Error, inspect database.getLastError() and re-establish the connection.
4. Serialize access to a single service instance to avoid Busy contention.

Example fix

// before
SFQueryResult r = service.querySimilarFunctions(queryInfo, listener, monitor);
// after
if (service.getStatus() != Status.Ready) {
    throw new IllegalStateException("BSim database not ready: " + service.getStatus());
}
SFQueryResult r = service.querySimilarFunctions(queryInfo, listener, monitor);

if (service.getStatus() != Status.Ready) {
    throw new IllegalStateException("BSim database not ready: " + service.getStatus());
}
SFQueryResult r = service.querySimilarFunctions(queryInfo, listener, monitor);

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

try {
    service.querySimilarFunctions(queryInfo, listener, monitor);
} catch (QueryDatabaseException e) {
    if (e.getMessage().contains("not established")) { /* (re)connect then retry */ }
}

When it happens

Trigger: Calling querySimilarFunctions before the service was connected/initialized, after it was closed/disposed, or while a previous query still marks the database Busy.

Common situations: Forgetting to setDatabase / connect before querying; calling query after service.dispose(); a prior query left the DB in Error state (auth/network failure); concurrent use of one service from two threads.

Related errors

• Connection to database not established
• Executable category already exists
• Function tag already exists
• Unable to connect to server
• No thresholds have been established

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