Nov 20, 20267 min read

Configure CORS on a Google Cloud Storage Bucket

How Cloud Storage evaluates CORS, a working configuration for signed URL uploads and downloads, the gcloud and Terraform commands to apply it, why the XML and JSON API endpoints behave differently, and how to keep browser uploads behind your own API instead.

Illustration for Configure CORS on a Google Cloud Storage Bucket

Cloud Storage sends no CORS headers until a bucket has a CORS configuration, so the first browser PUT to a signed URL dies in the console with a preflight error. The fix is a short JSON file, but the XML and JSON API endpoints treat it differently.

This guide covers the configuration fields, a setup that works for signed URL uploads, the errors that survive a correct config, and a way to avoid bucket CORS altogether.

How Does CORS Work in Cloud Storage?

A page on https://app.example.com that uploads to https://storage.googleapis.com/acme-uploads/... is making a cross-origin request. For anything beyond a simple GET, the browser first sends an OPTIONS preflight with Origin, Access-Control-Request-Method and Access-Control-Request-Headers, and only sends the upload if the bucket answers with matching CORS headers. The Cloud Storage CORS overview describes how each part of the bucket configuration maps to a response header.

Each entry in the configuration has four fields:

  • origin: the exact origins allowed, such as https://app.example.com, or * for any origin.
  • method: the HTTP methods allowed, from GET, HEAD, PUT, POST and DELETE. Leave OPTIONS out, because the browser sends it on its own.
  • responseHeader: the headers allowed on requests in a preflight and exposed to JavaScript on responses.
  • maxAgeSeconds: how long the browser caches the preflight result, with a default of 3600.

One detail differs from S3: responseHeader does double duty, covering both the request headers the browser may send and the response headers your code may read, so Content-Type and ETag go in the same list.

What Configuration Do Signed URL Uploads Need?

For browser uploads through V4 signed URLs from one frontend plus local development, this cors.json covers PUT uploads and GET downloads:

[ { "origin": ["https://app.example.com", "http://localhost:5173"], "method": ["GET", "HEAD", "PUT"], "responseHeader": ["Content-Type", "x-goog-resumable", "ETag"], "maxAgeSeconds": 3600 } ]

Apply it with gcloud storage and read it back to confirm what the bucket holds:

~
$ gcloud storage buckets update gs://acme-uploads --cors-file=cors.json$ gcloud storage buckets describe gs://acme-uploads --format="default(cors_config)"

The gcloud storage buckets update reference also has --clear-cors for removing the configuration. When a new rule seems to have no effect, the browser may still hold an earlier failed preflight for up to maxAgeSeconds, so clear the cache or test from a fresh profile before changing the rule again.

In Terraform, CORS is a nested block on the bucket resource rather than its own resource:

resource "google_storage_bucket" "uploads" { name = "acme-uploads" location = "EU" uniform_bucket_level_access = true cors { origin = ["https://app.example.com"] method = ["GET", "HEAD", "PUT"] response_header = ["Content-Type", "x-goog-resumable", "ETag"] max_age_seconds = 3600 } }

For resumable uploads, the signed URL starts the session with a POST carrying x-goog-resumable: start, so add POST to method if your frontend uses them.

Why Does the Browser Still Report a CORS Error?

When the configuration looks right and the browser still complains, the cause is often outside CORS. Work through these in order:

  • The request is going to the JSON API or the console endpoint. Only XML API URLs such as storage.googleapis.com/BUCKET/OBJECT and BUCKET.storage.googleapis.com evaluate your bucket configuration. The JSON API answers with default CORS headers regardless, and storage.cloud.google.com, the link the console shows for each object, does not allow CORS requests at all.
  • The origin does not match exactly. https://app.example.com, https://www.app.example.com and http://localhost:5173 are three different origins, and the scheme and port are part of each one.
  • A request header is missing from responseHeader. If the browser sends Content-Type or a custom x-goog-meta-* header that the URL was signed with, it must be in the list, or the preflight returns without CORS headers.
  • The signed URL is wrong. An expired URL, a content type that differs from the one used when signing, or a signature mismatch returns an error response, and the browser shows that as a CORS failure. Run the same request with curl to see the actual status code.
  • The request sends credentials. The XML API never returns Access-Control-Allow-Credentials, so a fetch with credentials: "include" fails. Signed URLs do not need cookies, so leave credentials off.

The CORS troubleshooting guide walks through the same checks, including how to flush a cached preflight with a lower maxAgeSeconds.

Is CORS a Security Control for the Bucket?

No, CORS only tells browsers which origins' JavaScript may read a response, and anyone with a signed URL can use it from curl whatever the CORS rules say. Access comes from IAM, uniform bucket-level access and short signed URL lifetimes, while CORS rules stay as narrow as your frontends need, as the MDN CORS guide explains for browsers in general.

How Does Encore Handle Browser Uploads to GCS?

Encore

Encore brings infrastructure from code, so the bucket is a TypeScript declaration in the service that writes to it, and on GCP it becomes a Cloud Storage bucket in your own project with access granted to that service. That makes a different upload path easy: the browser sends the file to your API on one origin, the API checks it and writes it to the bucket, and the only CORS policy is the one in encore.app.

Set up the app

Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

~
$ encore app create uploads-api --example=ts/hello-world$ cd uploads-api && mkdir -p uploads

The CORS settings in encore.app allow the frontend origin, including credentialed requests that carry the user's session cookie:

{ "id": "uploads-api", "global_cors": { "allow_origins_with_credentials": ["https://app.example.com"] } }

The service declares the bucket and a raw endpoint that reads the body with a size cap, checks the content type and writes the file:

// uploads/encore.service.ts import { Service } from "encore.dev/service"; export default new Service("uploads");
// uploads/uploads.ts import { api } from "encore.dev/api"; import { currentRequest } from "encore.dev"; import { Bucket } from "encore.dev/storage/objects"; export const attachments = new Bucket("attachments"); const MAX_BYTES = 25 * 1024 * 1024; const ALLOWED = ["image/png", "image/jpeg", "application/pdf"]; export const upload = api.raw( { expose: true, method: "PUT", path: "/attachments/:name" }, async (req, resp) => { const meta = currentRequest(); const name = meta?.type === "api-call" ? String(meta.pathParams.name) : ""; const contentType = req.headers["content-type"] ?? ""; if (!name || !ALLOWED.includes(contentType)) { resp.writeHead(415).end("unsupported content type"); return; } const chunks: Buffer[] = []; let size = 0; for await (const chunk of req) { size += chunk.length; if (size > MAX_BYTES) { resp.writeHead(413).end("file too large"); return; } chunks.push(chunk as Buffer); } const attrs = await attachments.upload(name, Buffer.concat(chunks), { contentType }); resp.writeHead(201, { "Content-Type": "application/json" }); resp.end(JSON.stringify({ name: attrs.name, size: attrs.size })); }, );

encore run serves this locally with object storage on your machine, so the browser upload works end to end before anything is deployed. When you deploy to your GCP project, Encore provisions the Cloud Storage bucket, and Encore provisions a service account for the service. For very large files you can switch to attachments.signedUploadUrl(name, { ttl: 900 }), and since the browser then talks to storage.googleapis.com directly, the bucket needs the CORS configuration from earlier in this guide.

An agent asked to accept a new file type changes ALLOWED and, if needed, the origin list in encore.app in the same diff, then tests the upload against the local bucket, with no console visit to edit bucket settings.

Best fit: apps on GCP that accept user uploads and want them in a Cloud Storage bucket in their own project, with the upload rules and the CORS policy kept next to the code.

GCS CORS Checklist

  • Send browser requests to XML API URLs, never to storage.cloud.google.com.
  • List exact origins, including local development, rather than * for upload buckets.
  • Put Content-Type, x-goog-resumable and any signed x-goog-meta-* headers in responseHeader.
  • Add ETag to responseHeader when JavaScript needs to read it.
  • Add POST when the frontend starts resumable uploads.
  • Leave credentials off browser requests to signed URLs.
  • Reproduce failures with curl before changing the CORS rules.

Frequently asked questions

How do I set CORS on a Google Cloud Storage bucket?

Write a JSON file with a list of entries that each set origin, method, responseHeader and maxAgeSeconds, then run gcloud storage buckets update gs://BUCKET --cors-file=cors.json. Check the result with gcloud storage buckets describe gs://BUCKET --format="default(cors_config)".

Why does my GCS signed URL upload fail with a CORS error?

Usually the origin in the bucket configuration does not match the page exactly, the browser sends a header such as Content-Type that is not listed in responseHeader, or the signed URL itself is invalid and the error response comes back without CORS headers. Signed URLs use the XML API endpoint, which only answers with CORS headers when the bucket configuration matches.

Does Cloud Storage support CORS with credentials?

No. The XML API endpoint, which serves signed URLs and storage.googleapis.com object URLs, never returns Access-Control-Allow-Credentials. Send requests without cookies, and authorize them with a signed URL instead.

Can I configure CORS per object or per folder in Cloud Storage?

No. CORS is set once per bucket and applies to every object in it. If two frontends need different rules, list both origins in the bucket configuration or use separate buckets.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders