googleapis/mcp-toolbox · error

ErrBinaryContent

ErrBinaryContent

Error message

cloud storage object is not valid UTF-8 text

What it means

ErrBinaryContent is returned by the Cloud Storage source's ReadObject when the object's bytes are not valid UTF-8. The MCP tool result channel only carries text today, so binary payloads cannot be faithfully returned; ProcessGCSError maps this to an Agent error so the LLM knows to stop asking for this object. A TODO notes the guard should be removed once non-text MCP content is supported.

Source

Thrown at internal/tools/cloudstorage/cloudstoragecommon/errors.go:43

	"cloud.google.com/go/storage"
	"github.com/googleapis/mcp-toolbox/internal/util"
	"google.golang.org/api/googleapi"
)

// ErrReadSizeLimitExceeded is returned by the source when an object/range
// would exceed the source's configured byte limit. ProcessGCSError maps this
// to an Agent error because the LLM can fix the call by narrowing the 'range'
// parameter.
var ErrReadSizeLimitExceeded = errors.New("cloud storage read size limit exceeded")

// ErrBinaryContent is returned by the source when an object's bytes are not
// valid UTF-8. The MCP tool result channel only carries text today, so binary
// payloads cannot be faithfully round-tripped; ProcessGCSError maps this to an
// Agent error so the LLM knows to stop asking for this object.
//
// TODO: when the toolbox supports non-text MCP content (embedded resources,
// images, blobs), remove this guard and return binary payloads directly.
var ErrBinaryContent = errors.New("cloud storage object is not valid UTF-8 text")

// ErrDestinationExists is returned by the download_object source method when
// the local destination file already exists and overwrite is false.
// ProcessGCSError maps this to an Agent error so the LLM can retry the call
// with overwrite=true.
var ErrDestinationExists = errors.New("download destination already exists")

// ProcessGCSError classifies an error from the Cloud Storage Go client into
// either an Agent Error (the LLM can self-correct by changing its input — bad
// request, missing bucket/object, unsatisfiable range) or a Server Error
// (infrastructure failure — auth, IAM denial, quota, 5xx, network
// cancellation). See DEVELOPER.md "Tool Invocation & Error Handling" for the
// wider rationale.
func ProcessGCSError(err error) util.ToolboxError {
	if err == nil {
		return nil
	}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Stop requesting this object as text; only UTF-8 text objects are supported.
2. Convert the object to UTF-8 text (e.g. upload an uncompressed/re-encoded copy) or export it as CSV/JSON text.
3. Download the object out-of-band (e.g. gsutil/gcloud or the download_object flow to a local file) if binary access is needed.

Example fix

// before: agent repeatedly reads a binary export
read_object(bucket="data", object="export.parquet") // -> ErrBinaryContent
// after: convert to text first, then read
// gsutil cp gs://data/export.parquet - && parquet-to-csv > export.csv && gsutil cp export.csv gs://data/
read_object(bucket="data", object="export.csv")

if errors.Is(err, cloudstoragecommon.ErrBinaryContent) {
    // stop retrying this object; fall back to download_object for local binary handling
}

When it happens

Trigger: Calling read_object on a GCS object whose downloaded bytes fail utf8.Valid — e.g. images (PNG/JPEG), archives (zip/gzip), PDFs, or text encoded in non-UTF-8 charsets like Latin-1.

Common situations: Pointing the agent at a bucket containing mixed media/exports; expecting a '.txt'-like object that is actually gzipped or UTF-16; legacy files saved in non-UTF-8 encodings.

Related errors

• ErrReadSizeLimitExceeded
• ErrDestinationExists
• unable to create client: %w
• error creating AlloyDB instance: %w
• error creating AlloyDB user: %w

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/4b362d02d14ac05c. Report an issue: GitHub.