pinpoint-apm/pinpoint · error · OracleConnectionStringException

unsupported token

Error message

unsupported token:<ch>

What it means

OracleNetConnectionDescriptorTokenizer.parse() tokenizes the descriptor character by character; characters classified as comma, backslash, double quote or single quote have no handling and immediately throw 'unsupported token:<ch>'. The tokenizer deliberately rejects punctuation it doesn't understand rather than guessing.

Solutions

  1. Replace comma-separated address lists with nested parentheses: (ADDRESS_LIST=(ADDRESS=...)(ADDRESS=...))
  2. Remove quotes around values — descriptor values are bare literals
  3. If a password or value contains quotes/backslashes, pass it via a separate connection property instead of embedding it in the URL
  4. Sanitize/normalize the descriptor (strip whitespace, quotes) before handing it to the parser

Example fix

// before
String url = "jdbc:oracle:thin:@(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=a)(PORT=1521)),(ADDRESS=(PROTOCOL=TCP)(HOST=b)(PORT=1521)))";
// after
String url = "jdbc:oracle:thin:@(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=a)(PORT=1521))(ADDRESS=(PROTOCOL=TCP)(HOST=b)(PORT=1521)))";
Defensive patterns

Strategy: validation

Validate before calling

static boolean hasUnsupportedChars(String descriptor) {
    for (char c : descriptor.toCharArray()) {
        if (c == ',' || c == '\\' || c == '"' || c == '\'') return true;
    }
    return false;
}
// reject/normalize before parsing

Try / catch

try {
    parser.parse(url);
} catch (OracleConnectionStringException e) {
    log.error("Oracle descriptor contains unsupported character (comma/quote/backslash): {}", url, e);
    throw new ConfigurationException("Unsupported character in descriptor", e);
}

Prevention

When it happens

Trigger: A connection descriptor containing a comma (e.g. ADDRESS_LIST entries separated by ',' instead of nested (ADDRESS_LIST=...)), or quotes/backslashes anywhere in the URL passed through the tokenizer.

Common situations: Writing multi-address lists with commas copied from other formats; surrounding values with quotes in config; passwords containing quotes/backslashes embedded directly in the descriptor; Windows-style escaped paths.

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/dfc1b020cb8d4c3d. Report an issue: GitHub.

Appendix: source

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

            }

            switch (ch) {
                case TOKEN_KEY_START:
                    this.tokenList.add(TOKEN_KEY_START_OBJECT);
                    break;
                case TOKEN_EQUAL:
                    this.tokenList.add(TOKEN_EQUAL_OBJECT);
                    break;
                case TOKEN_KEY_END:
                    this.tokenList.add(TOKEN_KEY_END_OBJECT);
                    break;
                case TOKEN_COMMA:
                case TOKEN_BKSLASH:
                case TOKEN_DQUOTE:
                case TOKEN_SQUOTE:
                    // TODO handle these tokens.
                    // Need to study how these tokens are used.
                    throw new OracleConnectionStringException("unsupported token:" + ch);
                default:
                    String literal = parseLiteral();
                    addToken(literal, TYPE_LITERAL);
            }
        }
        this.tokenList.add(TOKEN_EOF_OBJECT);
    }

    String parseLiteral() {
        int start = trimLeft();

        for (position = start; position < connectionString.length(); position++) {
            final char ch = connectionString.charAt(position);
            switch (ch) {
                case TOKEN_EQUAL:
                case TOKEN_KEY_START:
                case TOKEN_KEY_END:
                    int end = trimRight(position);

View on GitHub (pinned to 744c3d3075)