pinpoint-apm/pinpoint · error · OracleConnectionStringException

description_list node not found

Error message

description_list node not found

What it means

DescriptionList wraps a list of DESCRIPTION nodes parsed from an Oracle connection descriptor. When given a terminal key/value it verifies the key is DESCRIPTION_LIST; anything else throws OracleConnectionStringException('description_list node not found').

Source

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

package com.navercorp.pinpoint.plugin.jdbc.oracle.parser;

import java.util.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Set;

import static com.navercorp.pinpoint.plugin.jdbc.oracle.parser.ParserUtils.compare;

public class DescriptionList implements DatabaseSpec {
    public static final String DESCRIPTION_LIST = "description_list";

    private final List<Description> descriptionList = new ArrayList<>();

    public DescriptionList(KeyValue<?> keyValue) {
        if (keyValue instanceof KeyValue.TerminalKeyValue) {
            if (!compare(DESCRIPTION_LIST, keyValue)) {
                throw new OracleConnectionStringException(DESCRIPTION_LIST + " node not found");
            }
        }
        if (keyValue instanceof KeyValue.KeyValueList) {
            KeyValue.KeyValueList kvList = (KeyValue.KeyValueList) keyValue;
            for (KeyValue<?> desc : kvList.getValue()) {
                if (compare(Description.DESCRIPTION, desc)) {
                    Description description = new Description(desc);
                    this.descriptionList.add(description);
                }
            }
        }
    }

    public List<Description> getDescriptionList() {
        return descriptionList;
    }

    @Override

View on GitHub (pinned to 744c3d3075)

Solutions

1. Verify the URL's top node is exactly (DESCRIPTION_LIST=(DESCRIPTION=...)) when the descriptor is list-based
2. Or switch to a single (DESCRIPTION=...) URL, which parses via Description
3. Check key spelling and casing
4. Validate the descriptor with tnsping

Example fix

// before
jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=...)(CONNECT_DATA=...))
// after (list form)
jdbc:oracle:thin:@(DESCRIPTION_LIST=(DESCRIPTION=(ADDRESS=...)(CONNECT_DATA=...)))

if (!jdbcUrl.contains("(DESCRIPTION_LIST")) {
    // use single-DESCRIPTION parsing path instead of DescriptionList
}

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

try {
    new DescriptionList(keyValue);
} catch (OracleConnectionStringException e) {
    // top node is not DESCRIPTION_LIST — try Description for single-node descriptors
}

When it happens

Trigger: Parsing jdbc:oracle:thin:@(DESCRIPTION_LIST=...) style URLs where the top-level node key is not exactly DESCRIPTION_LIST — e.g. a single DESCRIPTION node, ADDRESS node, or a misspelled key.

Common situations: Using a descriptor form the parser doesn't expect (single DESCRIPTION passed where DESCRIPTION_LIST is required); typo'd or lowercased key; hand-built TNS descriptor string.

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

• description node not found
• invalid oracle jdbc url. expected token:(thin or oci) url:<u
• parsing error. expected token:'EOF' token:null
• parsing error. expected token:'EOF' token:<eof>
• Syntax error. lookAheadToken is null

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