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.

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.
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.
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:
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.
When the configuration looks right and the browser still complains, the cause is often outside CORS. Work through these in order:
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.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.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.curl to see the actual status code.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.
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.
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.
Run in your terminal to get started locally.
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.
storage.cloud.google.com.* for upload buckets.Content-Type, x-goog-resumable and any signed x-goog-meta-* headers in responseHeader.ETag to responseHeader when JavaScript needs to read it.POST when the frontend starts resumable uploads.curl before changing the CORS rules.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)".
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.
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.
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.