t8y2/dbx · error

unknown method: %s

Error message

unknown method: %s

What it means

dispatch routes the agent protocol's method names to concrete handlers (connect, test_connection, metadata, query, paged_query, transaction, ddl, disconnect, shutdown). Any unrecognized method falls into the default branch and returns 'unknown method: %s'.

Source

Thrown at agents/drivers/iotdb/main.go:394

		result, err := s.executeQueryPage(queryOptionsFromParams(params), intParam(params, "pageSize"))
		return result, false, err
	case "fetch_query_page", "fetch_table_read_page":
		result, err := s.fetchQueryPage(stringParam(params, "sessionId"), intParam(params, "pageSize"))
		return result, false, err
	case "close_query_session", "close_table_read_session":
		return s.closeQuerySession(stringParam(params, "sessionId")), false, nil
	case "execute_transaction":
		result, err := s.executeStatements(params, true)
		return result, false, err
	case "execute_batch":
		result, err := s.executeStatements(params, false)
		return result, false, err
	case "disconnect":
		return map[string]bool{"ok": true}, false, s.disconnect()
	case "shutdown":
		return map[string]bool{"ok": true}, true, s.disconnect()
	default:
		return nil, false, fmt.Errorf("unknown method: %s", method)
	}
}

func handshakeResult(multiSession bool) map[string]any {
	capabilities := []string{
		"connect", "test_connection", "metadata", "query", "paged_query", "transaction", "ddl", "structured_error_v1",
	}
	if multiSession {
		capabilities = append(capabilities, "multi_session")
	}
	return map[string]any{
		"protocolVersion":      protocolVersion,
		"agentProtocolVersion": protocolVersion,
		"capabilities":         capabilities,
	}
}

func testConnection(params connectParams) (map[string]any, error) {

View on GitHub (pinned to c0390bff16)

Solutions

1. Check the method name against the capabilities listed in handshakeResult.
2. Align the client and agent to the same protocol version.
3. Negotiate capabilities via the handshake and only call advertised methods.
4. Log the %s value from the error to see exactly what string was sent.

Example fix

// before
method = "executeQuery"
// after
method = "query"

var supportedMethods = map[string]bool{
    "connect": true, "test_connection": true, "metadata": true,
    "query": true, "paged_query": true, "transaction": true,
    "ddl": true, "disconnect": true, "shutdown": true,
}
func methodSupported(m string) bool { return supportedMethods[m] }

func isUnknownMethodErr(err error) bool {
    return err != nil && strings.HasPrefix(err.Error(), "unknown method: ")
}

result, _, err := s.dispatch(method, args)
if isUnknownMethodErr(err) {
    return fmt.Errorf("agent does not support %q; check negotiated capabilities", method)
}

When it happens

Trigger: Sending a request with a misspelled method (e.g. 'execute_query' instead of 'query'), wrong casing, or a method from a newer/older protocol version not implemented by this build.

Common situations: Client and agent protocol version mismatch after an upgrade; hand-written clients inventing method names; calling 'transaction' or 'ddl' on a build whose handshake did not advertise those capabilities.

Related errors

• unknown method: %s
• unknown method: %s
• unknown method: %s
• unknown method: %s
• unknown method: %s

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/0e14f7be7d5583b3. Report an issue: GitHub.