{"record":{"id":"e225a16fa4294e82","repo":"googleapis/mcp-toolbox","slug":"errdestinationexists","errorCode":"ErrDestinationExists","errorMessage":"download destination already exists","messagePattern":"download destination already exists","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/tools/cloudstorage/cloudstoragecommon/errors.go","lineNumber":49,"sourceCode":"// 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\n\t// Transport-level cancellation/timeout — treat as infrastructure. These\n\t// checks come first because a wrapped googleapi.Error on top of a\n\t// cancelled context should still surface as a server error.\n\tif errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {\n\t\treturn util.NewClientServerError(\n\t\t\t\"cloud storage request cancelled or timed out\",","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/tools/cloudstorage/cloudstoragecommon/errors.go#L31-L67","documentation":"ErrDestinationExists is returned by the download_object source method when the local destination file already exists and overwrite is false. DownloadObject maps the underlying os.ErrExist from file creation to this sentinel, and ProcessGCSError classifies it as an Agent error so the LLM can retry with overwrite=true. It prevents accidental clobbering of existing local files.","triggerScenarios":"Calling download_object (GCS) where os.OpenFile/os.Create on the destination path returns os.ErrExist — i.e. the local file exists and overwrite was not set to true.","commonSituations":"Re-running a download step after a previous successful run left the file in place; agent retrying a partially completed workflow; a fixed destination filename reused across downloads.","solutions":["Retry the download call with overwrite=true to replace the existing destination file.","Choose a different destination path that does not exist.","Delete or move the existing file before retrying if preservation of the old copy matters."],"exampleFix":"// before\ndownload_object(bucket=\"exports\", object=\"report.csv\", destination=\"/tmp/report.csv\") // -> ErrDestinationExists\n// after\ndownload_object(bucket=\"exports\", object=\"report.csv\", destination=\"/tmp/report.csv\", overwrite=true)","handlingStrategy":"validation","validationCode":"if _, err := os.Stat(destination); err == nil && !overwrite {\n    destination = fmt.Sprintf(\"%s.%d.bak\", destination, time.Now().Unix())\n}","typeGuard":null,"tryCatchPattern":"if errors.Is(err, cloudstoragecommon.ErrDestinationExists) {\n    // retry once with overwrite=true or pick a new destination\n}","preventionTips":["Use unique, timestamped destination filenames per download run.","Check os.Stat on the destination before calling download_object.","Explicitly set overwrite=true when re-downloading the same report path is intended."],"tags":["gcp","cloud-storage","file-exists","overwrite","agent-correctable"],"backgroundTag":"destination-file-exists","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"}