Skip to content
CC Switch WikiUnofficial Community Wiki

S3 HEAD bucket failed: 404 Not Found - CC Switch

Quick fix

If the endpoint contains the bucket name, remove the bucket field from the config to prevent path duplication.

Symptom

Section titled “Symptom”
Error output
S3 HEAD bucket 失败: 404 Not Found
(https://mybucket.oss-cn-zhongwei.aliyuncs.com/mybucket/)
English translation

S3 HEAD bucket failed: 404 Not Found (https://mybucket.oss-cn-zhongwei.aliyuncs.com/mybucket/)

Cause

Section titled “Cause”

When using S3-compatible storage (such as Alibaba Cloud OSS or Cloudflare R2) with a virtual-hosted style endpoint (where the host part includes the bucket name, e.g., `https://mybucket.oss-cn-zhongwei.aliyuncs.com`), cc-switch v3.18.0 has a URL construction logic flaw.

The `is_aws_endpoint` function only recognizes `amazonaws.com`, causing non-AWS endpoints to be incorrectly classified into the path-style branch. In path-style mode, the program forcibly appends the bucket name to the URL path. Since the user's endpoint already contains the bucket name, this results in path duplication (e.g., `/mybucket/`), causing HEAD requests to return 404 Not Found. Additionally, upload operations will store objects under incorrect prefixes.

Fix

Section titled “Fix”

  1. Open the cc-switch sync settings interface and locate the S3/OSS storage configuration area.

  2. Check the Endpoint address. If the Endpoint is in the format https://<bucket>.oss-cn-<region>.aliyuncs.com, leave the 'Bucket' or 'Bucket Name' configuration item empty or delete its content.

    在 UI 配置中：
    # Endpoint: https://mybucket.oss-cn-zhongwei.aliyuncs.com (保持不变)
    # Bucket: [留空]

  3. Save the configuration and retest the connection. The URL should now correctly resolve without duplicate bucket names, and HEAD requests should succeed.

Affected Versions

Section titled “Affected Versions”
ToolClaude Code
Version3.18.0
PlatformsLinux

Source Issues

Section titled “Source Issues”

This page is distilled from 2 real issues

FAQ

Section titled “FAQ”
Why do I need to delete the bucket from the config if it's already in my Endpoint?
Because this version of the code cannot automatically recognize non-AWS virtual-hosted style endpoints. If you do not remove the bucket field from the configuration, the program will append the bucket name again in the URL path, resulting in a 404 error.
I have already uploaded files. Can I read them after fixing this?
It may not be possible to read them directly. Due to the previous bug, files might have been stored under an incorrect nested prefix (e.g., `mybucket/cc-switch-sync/v2/...`). You need to manually check the storage console and move files to the correct root directory, or accept that data is scattered in incorrect paths.
Does this bug only affect Alibaba Cloud OSS?
No. Any S3-compatible service using virtual-hosted style endpoints that are not recognized by `is_aws_endpoint` will be affected, including Cloudflare R2, Backblaze B2, etc.
Section titled “Related problems”
command turns into cmd automatically and the mcp service fails to connect - Claude CodeEdit MCP config inside the cc-switch UI so it is not overwritten, and correct npx commands rewritten wrongly as cmd by hand.3 issues mergedAuthorization header is badly formattedTurn "local routing" on in cc-switch and set the API format to native, resolving the 400 auth header error connecting GitHub Copilot to Claude Code.2 issues mergedcc-switch import / cloud sync failures: foreign keys, read-only database, overwritesUpgrade cc-switch and avoid syncing provider_health or a read-only db; after picking a file, click 导入 (Import) rather than 保存 (Save).25 issues merged

This is an unofficial community wiki with no affiliation to the cc-switch authors or the project itself. Its content is compiled from the project's public GitHub issues. This site distributes no software.