What causes "description node not found" in pinpoint-apm/pinpoint?

Ensure the URL contains a full descriptor starting with (DESCRIPTION=(ADDRESS=...)(CONNECT_DATA=...))

pinpoint-apm/pinpoint · error · OracleConnectionStringException

description node not found

Error message

description node not found

What it means

Description.mapping(KeyValue) parses an Oracle net connection descriptor. It requires the top-level node of the (DESCRIPTION=...) string to be the DESCRIPTION key; if the current key/value is not DESCRIPTION it throws OracleConnectionStringException('description node not found').

Source

Thrown at agent-module/plugins/oracle-jdbc/src/main/java/com/navercorp/pinpoint/plugin/jdbc/oracle/parser/Description.java:47

    public static final String DESCRIPTION = "description";

    private String serviceName;
    private String sid;
    private final ArrayList<Address> addressList = new ArrayList<>();

    public Description() {
    }

    public Description(KeyValue<?> keyValue) {
        Objects.requireNonNull(keyValue, "keyValue");

        mapping(keyValue);
    }


    private void mapping(KeyValue<?> keyValue) {
        if (!compare(DESCRIPTION, keyValue)) {
            throw new OracleConnectionStringException(DESCRIPTION  + " node not found");
        }
        if (!(keyValue instanceof KeyValue.KeyValueList)) {
            return;
        }
        final KeyValue.KeyValueList keyValueList = (KeyValue.KeyValueList) keyValue;
        for (KeyValue<?> kv : keyValueList.getValue()) {
            if (compare("address", kv)) {
                if (kv instanceof KeyValue.KeyValueList) {
                    final KeyValue.KeyValueList addressList = (KeyValue.KeyValueList) kv;
                    String host = null;
                    String port = null;
                    String protocol = null;
                    for (KeyValue<?> addressKv : addressList.getValue()) {
                        if (addressKv instanceof KeyValue.TerminalKeyValue) {
                            final KeyValue.TerminalKeyValue terminal = (KeyValue.TerminalKeyValue) addressKv;
                            if (compare("host", terminal)) {
                                host = terminal.getValue();
                            } else if (compare("port", terminal)) {

View on GitHub (pinned to 744c3d3075)

Solutions

Ensure the URL contains a full descriptor starting with (DESCRIPTION=(ADDRESS=...)(CONNECT_DATA=...))
Check the top-level token is exactly DESCRIPTION
Use a standard host:port/service_name URL if you don't need a TNS descriptor
Test the descriptor with tnsping to confirm it is valid TNSNAMES syntax

Example fix

// before
jdbc:oracle:thin:@(ADDRESS=(PROTOCOL=TCP)(HOST=h)(PORT=1521))
// after
jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=h)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=orcl)))

Defensive patterns

Strategy: try-catch

Validate before calling

String url = jdbcUrl.substring(jdbcUrl.indexOf('@') + 1);
if (!url.startsWith("(DESCRIPTION")) {
    // fall back to host:port/sid parsing or reject before invoking the parser
}

Type guard

static boolean isDescriptionDescriptor(String u) {
    int at = u.indexOf('@');
    return at >= 0 && u.substring(at + 1).trim().toUpperCase().startsWith("(DESCRIPTION");
}

Try / catch

try {
    new Description(keyValue);
} catch (OracleConnectionStringException e) {
    // descriptor lacks a DESCRIPTION node — rewrite the JDBC URL or fall back
}

Prevention

Only pass full (DESCRIPTION=...) descriptors to the parser
Use host:port/service_name URLs when a TNS descriptor is not required
Validate descriptors with tnsping first

When it happens

Trigger: Parsing a JDBC URL of the form jdbc:oracle:thin:@(DESCRIPTION=...) whose descriptor's top node is not DESCRIPTION — e.g. it is ADDRESS_LIST, CONNECT_DATA, or malformed so the first key parsed isn't DESCRIPTION.

Common situations: URL uses shorthand forms like jdbc:oracle:thin:@host:port:sid or @(ADDRESS=(...)) that aren't full DESCRIPTION descriptors; typos like DESCRIPTIONS= or lowercase/extra whitespace confusing the key compare.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/6d57efcd5674761a. Report an issue: GitHub.