Use the export job row as the only source of truth for the object key. If the worker that writes the object and the handler that builds the browser download link each compute the key from tenant data, you don't have one system — you have two, and a 404 from object storage is the first moment they admit they disagree. Everything below is about making that disagreement visible before a customer does the reporting for you.

The 404 is honest. Your logs usually aren't.

I teach this with a media catalog, because it makes the access-control question unavoidable: a photo library holds a few hundred thousand product images, and each tenant can ask for a tenant-scoped export — a zip of their own images plus a CSV manifest. A background job builds it, the UI polls until the job says ready, and then the browser follows a download link. When that link returns 404 not found, you are looking at one of three separate bugs wearing the same costume, and troubleshooting them as one thing is why the ticket stays open for a week.

Why does a browser download link return 404 after an export job finishes?

Three causes, in the order I'd check them.

The first is a wrong object key prefix. Object stores are flat namespaces with a delimiter convention, not directories, so exports/tenant-42/ and exports/tenant=42/ are not two views of one folder — they're unrelated names that happen to look similar in a console. Prefix drift shows up when the writer and the reader build the key independently: one reads tenant.id, the other reads tenant.slug; one prepends the environment, the other doesn't; one trims the leading slash and the other leaves it, producing a first segment that is the empty string. Keys are byte-exact and case-sensitive. A single character of drift is a permanent 404 for that tenant, and only that tenant, which is exactly the shape that makes people blame "eventual consistency" instead of reading the two strings side by side.

The second is job timing — the actual race condition. Large exports go up as a multipart upload, and the parts are not addressable as an object until the completion call returns; the upload is only assembled into a readable object at that point. If your worker flips status = ready in the database and completes the upload afterwards, you have published a link to an object that doesn't exist yet. Same bug, smaller window, if the row commits before the completion call's response is handled.

The third is delivery. Everything between the browser and the bucket — your API, a redirect, a CDN, a proxy — can turn an existence question into a permissions question and back again.

The before/after that removes two of the three causes

Picture the bad version as two arrows pointing at one bucket. The worker computes a key and writes. The download handler computes a key and reads. Nothing connects them except a convention in someone's head.

Now redraw it: the worker computes the key once, writes the object, confirms the object is readable, and then records that exact string on the job row. The handler reads the row. It is not allowed to recompute anything.

// One function builds the key. Nothing downstream recomputes it. export function exportObjectKey(tenantId: string, jobId: string): string { return `exports/tenant-${tenantId}/${jobId}/product-images.zip`; } export async function finishExport(job: ExportJob, store: ObjectStore, db: Db) { const key = exportObjectKey(job.tenantId, job.id); const { size } = await store.putObject({ bucket: "media-exports", key, body: job.archive }); // Multipart uploads are readable only after completion returns. // Confirm it, then publish. Never the other way around. const head = await store.headObject({ bucket: "media-exports", key }); if (!head) throw new Error(`export ${job.id}: object not readable after write`); await db.exportJobs.update(job.id, { status: "ready", objectKey: key, objectBytes: size, committedAt: new Date().toISOString(), }); } 

That ordering is the whole fix for the race. The job row is the commit point; the storage write happens strictly before it, and ready means "I have already read this object back", not "I have finished sending bytes". Wrong-prefix 404s disappear for a different reason: there is no second implementation left to drift.

What does access control do to a 404 that you didn't expect?

This is where the delivery choice stops being cosmetic. A public object with a plain URL is the simplest thing that can possibly work — no signing, no expiry, cacheable by every layer for free. It also means the export of one tenant's catalog is retrievable by anyone who has or guesses the key, which for tenant-scoped data is usually the end of the conversation.

So you sign. Keep the bucket private, serve a short-lived signed URL from an endpoint that already knows the caller's tenant, and the access decision happens in code you own.

The catch is that a private bucket makes the status codes ambiguous on purpose. A caller without permission to list a bucket gets an access-denied response for a key that doesn't exist, because telling them "no such key" would confirm what isn't there — so a real missing-object bug can surface as 403, and a gateway configured to hide existence can report a permissions failure as 404. Expiry adds a second flavour: a link that worked ninety seconds ago and fails now is a TTL problem, not a storage problem. Neither is visible from the browser's status code, which is why the storage layer's own response has to be logged at the moment it happens.

app.get("/exports/:id/download", async (req, res) => { const job = await db.exportJobs.find(req.params.id, req.tenantId); if (!job) return deny(res, "job_not_found"); if (job.status !== "ready") return deny(res, "job_not_ready"); const head = await store.headObject({ bucket: "media-exports", key: job.objectKey }); if (!head) { log.warn("export.download.miss", { tenant: req.tenantId, job: job.id, key: job.objectKey, // recorded at write time committedAt: job.committedAt, cause: "object_missing_at_read", }); return deny(res, "object_unavailable"); } const url = await store.signedGetUrl({ bucket: "media-exports", key: job.objectKey, expiresIn: 300, }); log.info("export.download.signed", { tenant: req.tenantId, job: job.id, key: job.objectKey }); res.redirect(302, url); }); 

Five minutes of TTL is a starting point, not a law. Long enough for a slow connection to start the transfer, short enough that a leaked link is worthless by the time it reaches a support thread.

The three log lines that tell the causes apart

An export download that 404s should be a zero-rate event, which makes it one of the rare things worth alerting on directly rather than through a percentile. My rule: any export.download.miss in a five minute window pages, because the expected count is zero and the signal is never noisy in a system that records its own keys.

What you record matters more than where you send it. Three fields separate the three bugs: the key that was written, the key that was requested, and the timestamp the object was confirmed readable. Print them on one line, in the same order, every time.

{"event":"export.download.miss","tenant":"t_4417","job":"exp_91c2", "key_requested":"exports/tenant-4417/exp_91c2/product-images.zip", "key_recorded":"exports/tenant=4417/exp_91c2/product-images.zip", "committed_at":"2026-09-11T08:14:02Z","cause":"object_missing_at_read"} 

You don't need a dashboard to read that one. The prefix drifted.

What the browser sees What it usually is The field that proves it
404 right after "ready" appeared Job published before the upload completed committed_at is null or later than the ready timestamp
404 for one tenant, forever Wrong object key prefix key_requested differs from key_recorded
404 that heals itself minutes later A negative response cached at an edge or proxy cache status header on the failing request
404 that a retry never fixes The object was never written worker log with the byte count it thought it wrote

Two objections come up every time I walk through this.

"Our bucket is public, so permissions can't be the problem." True, and it moves the problem rather than removing it: a public prefix plus a CDN means a 404 can be cached at the edge, so a three second race condition becomes a ten minute dead link for that customer while the object sits there, perfectly fine, behind a cached miss. Public delivery also gives you nothing to revoke when an export URL ends up in a shared inbox.

"We retry the download, so the race is handled." Retries paper over timing and hide naming. A retry loop against a wrong prefix will never succeed, it just makes the error rate look gentler, and a browser following a redirect isn't running your retry code at all. Retry the HEAD on the server if you like — a couple of attempts with backoff is reasonable while a replica catches up — but treat a miss after that as a bug, not weather.

One honest limitation: none of this helps with eventual consistency across regions. Single-object read-after-write in the major stores is strongly consistent today, so a write you confirmed is a write you can read; asynchronous cross-region replication and multi-region read replicas are a different mechanism with their own lag, and if you serve a download from a replica you can get a 404 for an object that definitely exists. Stick with reading from the primary region for freshly written exports, or record which region the object landed in and sign against that one. I'm not aware of a shortcut that gives you both, and if your compliance rules force the export into a specific region, that constraint wins over delivery convenience anyway.

Three fields, one commit point, one function that owns the key. The rest is bookkeeping.

References