error processing GCP request: unable to execute query: bigquery: nil parameter

[dobesv]

Prerequisites

• I've searched the current open issues
• I've updated to the latest version of Toolbox

Toolbox version

1.0.0

Environment

Running container in kubernetes

        image: us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:0.31.0
        args: ["--config-folder", "/app/tools/", "--address", "0.0.0.0", "--port", "5000"]

Client

1. Client: kagent (python ADK)
2. Version: latest from git
3. Example: If possible, please include your code of configuration:

Tool config:

kind: tool
name: search_staging_logs
type: bigquery-sql
source: bigquery-staging-logs
statement: |
  SELECT
    FORMAT_TIMESTAMP('%Y-%m-%dT%H:%M:%SZ', timestamp) as timestamp,
    level,
    container,
    pod,
    namespace,
    message,
    JSON_EXTRACT_SCALAR(log, '$.err.message') as error_message,
    JSON_EXTRACT_SCALAR(log, '$.err.name') as error_name,
    log
  FROM `formative-dev-and-staging.logs.staging`
  WHERE timestamp BETWEEN @start_time AND @end_time
    AND (@level IS NULL OR @level = '' OR level = @level)
    AND (@message_pattern IS NULL OR @message_pattern = '' OR message LIKE @message_pattern)
    AND (@pod IS NULL OR @pod = '' OR pod LIKE @pod)
    AND (@container IS NULL OR @container = '' OR container = @container)
    AND (@namespace IS NULL OR @namespace = '' OR namespace = @namespace)
  ORDER BY timestamp DESC
  LIMIT @max_results
description: >
  Search staging cluster Kubernetes container logs. Use message_pattern
  with SQL LIKE syntax (% as wildcard). Use pod with LIKE syntax for prefix
  matching (e.g. 'nginx%'). Time parameters use RFC3339 format (e.g.
  '2026-01-15T10:30:00Z').
parameters:
  - name: start_time
    type: string
    description: Start of time range in RFC3339 format (e.g. '2026-01-15T10:30:00Z')
  - name: end_time
    type: string
    description: End of time range in RFC3339 format
  - name: level
    type: string
    description: "Log level filter (e.g. 'error', 'warn', 'info')"
    required: false
    default: null
  - name: message_pattern
    type: string
    description: "Pattern to search in log messages (SQL LIKE syntax, use % as wildcard)"
    required: false
    default: null
  - name: pod
    type: string
    description: "Pod name filter (SQL LIKE syntax, e.g. 'graphql-api-%')"
    required: false
    default: null
  - name: container
    type: string
    description: "Container name filter for exact match (e.g. 'graphql', 'bullworker')"
    required: false
    default: null
  - name: namespace
    type: string
    description: Kubernetes namespace filter
    required: false
    default: null
  - name: max_results
    type: integer
    description: Maximum number of results to return
    default: 100
    minValue: 1
    maxValue: 10000

Request:

{
  "container": "workflow-bot",
  "end_time": "2026-01-23T10:30:00Z",
  "max_results": 10,
  "namespace": "workflow-bot",
  "start_time": "2026-01-23T10:00:00Z"
}

Response:

error processing GCP request: unable to execute query: bigquery: nil parameter

Expected Behavior

The input provides all required parameters, so the query should have been run.

Current Behavior

A very opaque error is returned indicating a nil parameter, but not which parameter was nil. Assuming the request was actually invalid, detailed guidance should be given to the agent on how to rectify the request.

error processing GCP request: unable to execute query: bigquery: nil parameter

Steps to reproduce?

I have not figured out a minimal reproduction for this yet.

Additional Details

No response

[anubhav756]

Hi @dobesv, thanks for reporting this issue!

The tool seems to crash when you leave out optional settings (like level or pod). 🤔

@duwenxin99, just wanted to check if you have more context around the potential root-cause?

IIUC, BigQuery needs to know what kind of data (like text or number) a param is, even if it is left empty. Could this be because the code just sends an empty value without a type, which confuses BigQuery and causes the error?

CC: @averikitsch

[duwenxin99]

I assume it's because some of the parameters don't accept nil values. @Genesis929 could you provide more insights into this? Thank you!

[Deeven-Seru]

Hi @anubhav756 , @duwenxin99 ,@dobesv I dug into the code and can confirm what’s happening.

Root cause: when an optional parameter is omitted, it ends up as nil in paramsMap. The BigQuery tool currently always builds query parameters from that map, so if we send QueryParameter{Value: nil} to BigQuery. BigQuery doesn’t accept untyped nils, which explains the bigquery: nil parameter error.

Snippet (from internal/tools/bigquery/bigquerysql/bigquerysql.go):

  value := paramsMap[name]           // nil if omitted                                                                 
  highLevelParams = append(highLevelParams, bigquery.QueryParameter{                                                   
    Name:  paramNameForHighLevel,                                                                                      
    Value: value,                                                                                                      
  })                                                                                                                   

this will be fixed if we implement : if value == nil, we should send a typed NULL based on the schema (e.g., bigquery.NullString{Valid:false}, bigquery.NullInt64{Valid:false} , etc.) and keep the low‑level param type set. That makes @param IS NULL queries and behave as expected.