{"record":{"id":"419cf870a29c9166","repo":"apache/shardingsphere","slug":"can-not-locate-agent-jar-file-by-url-s","errorCode":null,"errorMessage":"Can not locate agent jar file by URL `%s`.","messagePattern":"Can not locate agent jar file by URL `(.+?)`\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"agent/core/src/main/java/org/apache/shardingsphere/agent/core/path/AgentPath.java","lineNumber":54,"sourceCode":"    /**\n     * Get agent root path.\n     *\n     * @param classLoader classLoader\n     * @return agent root path\n     */\n    public static File getRootPath(final ClassLoader classLoader) {\n        String classResourcePath = String.join(\"\", AgentPath.class.getName().replaceAll(\"\\\\.\", \"/\"), \".class\");\n        URL resource = Objects.requireNonNull(classLoader.getResource(classResourcePath), \"Can not locate agent jar file.\");\n        return getJarFile(resource.toString()).getParentFile();\n    }\n    \n    private static File getJarFile(final String url) {\n        try {\n            File result = new File(new URL(url.substring(url.indexOf(\"file:\"), url.indexOf('!'))).toURI());\n            AgentPreconditions.checkState(result.exists(), String.format(\"Can not locate agent jar file by URL `%s`.\", url));\n            return result;\n        } catch (final MalformedURLException | URISyntaxException ex) {\n            throw new IllegalStateException(String.format(\"Can not locate agent jar file by URL `%s`.\", url), ex);\n        }\n    }\n}\n","sourceCodeStart":36,"sourceCodeEnd":58,"githubUrl":"https://github.com/apache/shardingsphere/blob/e952770a215630a3659c75d64369168cd3e26b82/agent/core/src/main/java/org/apache/shardingsphere/agent/core/path/AgentPath.java#L36-L58","documentation":"Thrown by the Firebird frontend when a client issues a rollback referencing a transaction handle that the proxy's FirebirdTransactionIdGenerator does not consider active for the current connection. The proxy tracks Firebird transaction IDs per connection; a handle that was never opened, was already closed (committed/rolled back), or belongs to another connection is rejected with InvalidTransactionHandleException. It protects the proxy from operating on stale or foreign transaction state.","triggerScenarios":"Executing FirebirdRollbackTransactionCommandExecutor with a packet transaction id that fails FirebirdTransactionIdGenerator.isTransactionActive(connectionId, handle): rolling back twice with the same handle, rolling back after the transaction was already closed, using a handle from a previous/other connection session, or a client that fabricates or caches stale transaction ids.","commonSituations":"Firebird client drivers that reuse transaction handles across transactions; connection pooling where a pooled connection resumes with a handle from an earlier session; client library version that does not consume the handle returned by the proxy's start-transaction response; interleaved transactions on one connection.","solutions":["Make the client always use the handle returned by the most recent Firebird start-transaction (OK packet) response and discard it after commit or rollback.","Ensure the client does not send rollback twice for the same transaction handle; after the first rollback the handle is closed.","If a connection was reconnected/reset, start a new transaction instead of reusing a handle obtained before the reset.","Check proxy logs for the handle value in the message ('Invalid transaction handle: %d') and compare it against the handles the FirebirdTransactionIdGenerator issued for that connection id."],"exampleFix":"// before (client pseudo-code)\nconn.rollback(cachedTxHandle); // handle from a previous transaction\n\n// after\nint txHandle = conn.startTransaction(); // handle from start-transaction response\n// ... work ...\nconn.rollback(txHandle); // same, still-active handle\ntxHandle = -1; // never reuse","handlingStrategy":"validation","validationCode":"// Client-side: track the handle returned by start-transaction and clear it on terminal ops\nif (txHandle < 0) throw new IllegalStateException(\"No active transaction to roll back\");\nconn.rollback(txHandle);\ntxHandle = -1;","typeGuard":null,"tryCatchPattern":"// Server-side executor callers already map InvalidTransactionHandleException to a Firebird error packet;\n// clients should treat it as fatal for the transaction and start a new one:\ntry {\n    conn.rollback(txHandle);\n} catch (InvalidTransactionHandleException e) {\n    txHandle = -1; // discard stale handle\n    log.warn(\"Stale Firebird transaction handle discarded\", e);\n}","preventionTips":["Store the handle from the start-transaction response in a single variable per connection; overwrite on begin, null out on commit/rollback.","Never share or persist transaction handles across reconnects or pooled connection checkouts.","Wrap terminal operations in try/finally so a handle is always consumed exactly once."],"tags":["firebird","transaction","protocol","proxy-frontend"],"backgroundTag":null,"analyzedSha":"e952770a215630a3659c75d64369168cd3e26b82","analyzedAt":"2026-08-14T13:54:53.392Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}