{"record":{"id":"4b362d02d14ac05c","repo":"googleapis/mcp-toolbox","slug":"errbinarycontent","errorCode":"ErrBinaryContent","errorMessage":"cloud storage object is not valid UTF-8 text","messagePattern":"cloud storage object is not valid UTF-8 text","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/tools/cloudstorage/cloudstoragecommon/errors.go","lineNumber":43,"sourceCode":"\t\"cloud.google.com/go/storage\"\n\t\"github.com/googleapis/mcp-toolbox/internal/util\"\n\t\"google.golang.org/api/googleapi\"\n)\n\n// ErrReadSizeLimitExceeded is returned by the source when an object/range\n// would exceed the source's configured byte limit. ProcessGCSError maps this\n// to an Agent error because the LLM can fix the call by narrowing the 'range'\n// parameter.\nvar ErrReadSizeLimitExceeded = errors.New(\"cloud storage read size limit exceeded\")\n\n// ErrBinaryContent is returned by the source when an object's bytes are not\n// valid UTF-8. The MCP tool result channel only carries text today, so binary\n// payloads cannot be faithfully round-tripped; ProcessGCSError maps this to an\n// Agent error so the LLM knows to stop asking for this object.\n//\n// TODO: when the toolbox supports non-text MCP content (embedded resources,\n// images, blobs), remove this guard and return binary payloads directly.\nvar ErrBinaryContent = errors.New(\"cloud storage object is not valid UTF-8 text\")\n\n// ErrDestinationExists is returned by the download_object source method when\n// the local destination file already exists and overwrite is false.\n// ProcessGCSError maps this to an Agent error so the LLM can retry the call\n// with overwrite=true.\nvar ErrDestinationExists = errors.New(\"download destination already exists\")\n\n// ProcessGCSError classifies an error from the Cloud Storage Go client into\n// either an Agent Error (the LLM can self-correct by changing its input — bad\n// request, missing bucket/object, unsatisfiable range) or a Server Error\n// (infrastructure failure — auth, IAM denial, quota, 5xx, network\n// cancellation). See DEVELOPER.md \"Tool Invocation & Error Handling\" for the\n// wider rationale.\nfunc ProcessGCSError(err error) util.ToolboxError {\n\tif err == nil {\n\t\treturn nil\n\t}\n","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/tools/cloudstorage/cloudstoragecommon/errors.go#L25-L61","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Stop requesting this object as text; only UTF-8 text objects are supported.","Convert the object to UTF-8 text (e.g. upload an uncompressed/re-encoded copy) or export it as CSV/JSON text.","Download the object out-of-band (e.g. gsutil/gcloud or the download_object flow to a local file) if binary access is needed."],"exampleFix":"// before: agent repeatedly reads a binary export\nread_object(bucket=\"data\", object=\"export.parquet\") // -> ErrBinaryContent\n// after: convert to text first, then read\n// gsutil cp gs://data/export.parquet - && parquet-to-csv > export.csv && gsutil cp export.csv gs://data/\nread_object(bucket=\"data\", object=\"export.csv\")","handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"if errors.Is(err, cloudstoragecommon.ErrBinaryContent) {\n    // stop retrying this object; fall back to download_object for local binary handling\n}","preventionTips":["Prefer text-only buckets (CSV/JSON/md) for agent-facing reads.","Detect binary objects by extension/metadata before attempting text reads.","Download binaries to local files instead of inlining them into MCP results."],"tags":["gcp","cloud-storage","utf-8","binary-content","agent-correctable"],"backgroundTag":"non-utf8-binary-content","analyzedSha":"8cc6e09de2ad7b8bffc77751799585a1401a48eb","analyzedAt":"2026-09-05T01:10:36.887Z","contentChangedAt":"2026-09-05T01:10:36.887Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}