ClickHouse DB::Exception: Bad request parameter

The "DB::Exception: Bad request parameter" error in ClickHouse occurs when an HTTP request includes a query parameter that ClickHouse cannot accept. The BAD_REQUEST_PARAMETER error code is raised when the parameter name is unknown, the value is invalid, or the parameter conflicts with the current request context.

Impact

The HTTP request is rejected and no query is executed. The response typically includes a 400 status code along with the error details. Other concurrent requests are not affected.

Common Causes

1. An unrecognized query parameter name in the HTTP URL
2. A parameter value that does not match the expected type (for example, a string where an integer is required)
3. Conflicting parameters — such as specifying both query in the URL and in the POST body incorrectly
4. URL encoding issues that corrupt parameter names or values
5. Using a parameter that was deprecated or removed in the current ClickHouse version
6. Passing setting names with typos as URL parameters

Troubleshooting and Resolution Steps

1. Review the HTTP request you are sending. ClickHouse's HTTP interface accepts parameters as URL query strings:

   curl "http://localhost:8123/?query=SELECT+1&max_result_rows=100"
   

2. Verify that the parameter name is valid. Common parameters include query, database, default_format, user, password, and any ClickHouse setting name.

3. Check for URL encoding issues. Spaces should be encoded as + or %20, and special characters must be properly escaped:

   curl "http://localhost:8123/" --data-urlencode "query=SELECT 1"
   

4. If passing settings as parameters, confirm the setting name and expected value type:

   SELECT name, type, value FROM system.settings WHERE name = 'max_result_rows';
   

5. Avoid passing the same parameter multiple times. ClickHouse does not merge duplicate parameters:

   # Wrong — duplicate 'query' parameter
   curl "http://localhost:8123/?query=SELECT+1&query=SELECT+2"
   

6. If using a client library, check that it is formatting the HTTP request correctly. Enable HTTP debug logging in your client to see the raw request.

Best Practices

• Use POST requests with the query in the body to avoid URL length limits and encoding complications.
• Validate parameter names against the ClickHouse documentation before adding them to your HTTP requests.
• Use a well-maintained ClickHouse client library rather than crafting raw HTTP requests when possible.
• Log the full request URL (excluding sensitive parameters like passwords) to aid debugging when errors occur.

Frequently Asked Questions

Q: Can I pass ClickHouse settings as URL parameters?
A: Yes. Any ClickHouse setting can be passed as a URL query parameter, for example ?max_threads=4. The setting name must be spelled correctly and the value must be valid for that setting's type.

Q: Why do I get this error when my query works in clickhouse-client?
A: The clickhouse-client uses the native TCP protocol, while the HTTP interface has its own parameter handling. Ensure your HTTP request is correctly formatted, with the query either in the query parameter or the POST body.

Q: How do I pass credentials in the HTTP request?
A: You can use the user and password URL parameters, HTTP Basic Authentication headers, or the X-ClickHouse-User and X-ClickHouse-Key headers. Avoid putting passwords in URLs for security reasons.