Configure redirection for 404 errors to a custom page or an origin server - Object Storage Service

When a client requests an object that does not exist in a bucket, OSS can redirect the client to an origin server or a fallback URL instead of returning a 404 error. This keeps end-user access uninterrupted during data migrations and lets you serve custom error pages for missing objects.

How it works

Redirection uses a client-side redirect, not a server-side proxy. OSS does not fetch or stream content from the origin on behalf of the client.

When a request arrives, OSS evaluates it in this order:

If the object exists in the bucket — OSS serves the object normally.
If the object does not exist and a redirection rule matches — OSS returns an HTTP 3xx response with a Location header pointing to the target URL. The client (such as a browser) automatically follows the Location header and sends a new request to the target. OSS is not involved in that second request.
If the object does not exist but no rule matches — OSS returns a standard error (typically 404 Not Found or 403 Forbidden for private buckets).
If the request arrives through the standard OSS endpoint (http(s)://...aliyuncs.com) rather than a custom domain — redirection rules do not apply. OSS returns 400 Bad Request.

Serve a custom 404 page

Situation: A client hits a missing object in your bucket. Instead of receiving a generic 404 Not Found response, you want the client automatically redirected to a custom error page you control — for example, https://yourdomain.com/404.html.

Step 1: Attach a custom domain name

Before creating a redirection rule, attach a custom domain name to the bucket. Redirection rules apply only to requests made through a custom domain name attached to the bucket. Requests through the standard OSS endpoint (http(s)://...aliyuncs.com) return 400 Bad Request instead of triggering a redirect.

On the Buckets page, click the target bucket name.Buckets
In the left navigation pane, choose Bucket Settings > Domain Names, and then click Attach Domain.
In the Attach Domain panel, enter your custom domain name, such as customdomain.com.
If the bucket is in the Chinese mainland, the domain name must have an ICP filing.
Follow the prompts to configure CNAME parsing. Point your custom domain name to the CNAME address provided by OSS.

Step 2: Create a redirection rule

In the left navigation pane, choose Data Management > Mirroring-based Back-to-origin.
On the Mirroring-based Back-to-origin page, click Create Rule.

In the Create Rule panel, configure the following parameters:

Do not use 301 for an error page redirect. A 301 is a permanent redirect. Browsers and CDN nodes cache it aggressively, which makes the redirect difficult to modify or remove later.

Parameter	Value
Origin Fetch Type	Select Redirection
HTTP Status Code (Condition)	`404`
Origin URL	Select Redirect to a fixed URL
Protocol	`https`
Domain Name	The domain that hosts your error page, such as `yourdomain.com`
Path	The path of your error page, such as `404.html`
Redirection Code	`302` or `307`

Click OK.

Step 3: Verify the rule

Run the following curl command, replacing customdomain.com with the custom domain name attached to your bucket. Access an object that does not exist.

curl -I "http://customdomain.com/does-not-exist.html"

The expected response is a 302 status code and the correct Location header:

HTTP/1.1 302 Found
Server: AliyunOSS
Date: Wed, 03 Sep 2025 07:25:01 GMT
Content-Length: 0
Connection: keep-alive
x-oss-request-id: 68B7ED4D949F8A38365CC014
Location: https://yourdomain.com/404.html

Redirect during data migration

Situation: You are migrating data from a legacy origin server to OSS. Some objects are not yet synchronized. Instead of returning 404 errors for those missing objects, you want OSS to redirect the client to the corresponding path on your origin server. As you migrate each batch of objects, the client automatically retrieves them from OSS for migrated paths, and falls back to the origin for paths not yet migrated.

For example: your bucket uses the custom domain customdomain.com. Objects in examplefolder/ are not yet migrated. When a client requests customdomain.com/examplefolder/file.jpg, the rule redirects the client to https://yourdomain.com/examplefolder/file.jpg on the legacy origin server.

Step 1: Attach a custom domain name

On the Buckets page, click the target bucket name.Buckets
In the left navigation pane, choose Bucket Settings > Domain Names, and then click Attach Domain.
In the Attach Domain panel, enter your custom domain name, such as customdomain.com.
If the bucket is in the Chinese mainland, the domain name must have an ICP filing.
Follow the prompts to configure CNAME parsing. Point your custom domain name to the CNAME address provided by OSS.

Step 2: Create a redirection rule

In the left navigation pane, choose Data Management > Mirroring-based Back-to-origin.
On the Mirroring-based Back-to-origin page, click Create Rule.

In the Create Rule panel, configure the following parameters:

Important

Use 302, not 301. A 302 is a temporary redirect, which is correct for migration. A 301 is permanent — browsers and CDN nodes cache it aggressively. If you use 301, requests may continue going to the legacy origin server even after migration completes, which can cause serious production issues.

Select Add Prefix and Suffix, not Redirect to a fixed URL. The Add Prefix and Suffix pattern preserves the original request path, mapping examplefolder/file.jpg to yourdomain.com/examplefolder/file.jpg. Redirect to a fixed URL sends all requests to the same URL regardless of the original path.

Parameter	Value
Origin Fetch Type	Select Redirection
HTTP Status Code (Condition)	`404`
File Prefix (Condition)	The directory being migrated, such as `examplefolder/`. Leave blank to apply the rule to the entire bucket.
Origin URL	Select Add Prefix and Suffix
Protocol	The protocol supported by your origin server, such as `https`
Domain Name	The domain name of your origin server, such as `yourdomain.com`
Path	Leave blank. The Add Prefix and Suffix pattern automatically appends the requested path to the domain name.
Redirection Code	`302`

Click OK.

Step 3: Verify the rule

Run the following curl command, replacing customdomain.com with the custom domain name attached to your bucket:

curl -I "http://customdomain.com/examplefolder/does-not-exist.html"

The expected response is a 302 status code and a Location header that preserves the original path:

HTTP/1.1 302 Found
Server: AliyunOSS
Date: Wed, 03 Sep 2025 08:28:21 GMT
Content-Length: 0
Connection: keep-alive
x-oss-request-id: 68B7FC25107134303531344B
Location: https://yourdomain.com/examplefolder/does-not-exist.html

Step 4: Complete the migration

Migrate your remaining objects to OSS. For more information, see Migrate data to OSS.
Verify data integrity in OSS after the migration.
Narrow the rule scope progressively — for example, update File Prefix to target only subdirectories not yet migrated. Once all objects are in OSS, disable the rule to route all traffic directly to OSS.

Limitations

Feature	Support
Maximum rules per bucket	20
Rule matching order	Ascending by rule number (RuleNumber). The first matching rule is applied; subsequent rules are skipped.
Applicable domain type	Custom domain names only. Standard OSS endpoints (`...aliyuncs.com`) are not supported — they return `400 Bad Request`.
Prefix and suffix matching	Case-sensitive. Wildcard characters are not supported.
Multiple rules with the same prefix	Not supported. Each rule must use a distinct file prefix or suffix.
Server-side proxy	Not supported. Redirection is client-side only — OSS returns a `3xx` response and the client fetches content from the target.

FAQ

I configured a rule, but I still get a 404 or 403 error instead of a redirect. Why?

Check these three things in order:

Access domain name: Confirm you are using the custom domain name attached to the bucket, not the standard OSS endpoint. Using the OSS endpoint returns 400 Bad Request, not a redirect.
Bucket permissions: If the bucket is set to private, requests for non-existent objects return 403 Forbidden, not 404 Not Found. Add a 403 trigger condition to your rule alongside the 404 condition.
Rule priority: Check whether another rule with a lower rule number has already matched the request before yours.

Why does a double slash (//) appear in the redirected URL?

This is a path concatenation issue in the rule configuration. Check the File Prefix and Replace Prefix fields. For example, if the file prefix is path/, the replacement prefix should be new-path — not /new-path. Adding a leading slash creates a double slash after the domain name.

I updated a redirection rule, but the change has no effect. Why?

If you previously used a 301 permanent redirect, your browser or a CDN node has likely cached the old rule. Try clearing your browser cache, purging the CDN cache, or testing in a private browsing window.

Why do requests keep looping between redirects?

The redirect target is pointing back to a URL that triggers another OSS redirection rule, creating an infinite loop. Check that the target URL in the Location header does not resolve to the same custom domain name that has redirection rules configured. If you use a CDN in front of OSS, also check that the CDN's back-to-origin configuration is not sending requests back to the OSS custom domain.

How do I find out which rule matched a request?

OSS access logs do not record which redirection rule was matched. To identify the matching rule, progressively narrow the scope of your rules or temporarily disable other rules. You can also inspect the Location header in the 3xx response on the client side — the target URL reveals which rule was applied.

What's next

Migrate data to OSS