[GH-ISSUE #434] S3 Bucket Naming Limitations

kerem commented

2026-03-04 01:43:29 +03:00

Owner

Originally created by @nanodust on GitHub (Jun 13, 2016).
Original GitHub issue: https://github.com/s3fs-fuse/s3fs-fuse/issues/434

According to Amazon:
The rules for bucket names in the US East (N. Virginia) region allow bucket names to be as long as 255 characters, and bucket names can contain any combination of uppercase letters, lowercase letters, numbers, periods (.), hyphens , and underscores (_).

Yet, with S3FS, I cannot use any uppercase, periods, hyphens, or underscores in S3FS - if I do, I get an "s3fs: bucket name contains an illegal character"

this is true regardless of whether or not I use -ouse_path_request_style

In summary - s3fs works fine on buckets with no period, hyphen, underscore.

If any of those exist, I cannot find a way to allow s3fs to work.

I'm writing this issue in case it helps others...

meanwhile if there is a way to actually use (at least hyphens!) please let us know.

Thank you !

Originally created by @nanodust on GitHub (Jun 13, 2016). Original GitHub issue: https://github.com/s3fs-fuse/s3fs-fuse/issues/434 According to Amazon: The rules for bucket names in the US East (N. Virginia) region allow bucket names to be as long as 255 characters, and bucket names can contain any combination of uppercase letters, lowercase letters, numbers, periods (.), hyphens , and underscores (_). Yet, with S3FS, I cannot use any uppercase, periods, hyphens, or underscores in S3FS - if I do, I get an "s3fs: bucket name contains an illegal character" this is true regardless of whether or not I use -ouse_path_request_style In summary - s3fs works fine on buckets with no period, hyphen, underscore. If any of those exist, I cannot find a way to allow s3fs to work. I'm writing this issue in case it helps others... meanwhile if there is a way to actually use (at least hyphens!) please let us know. Thank you !

kerem closed this issue

2026-03-04 01:43:29 +03:00

kerem commented

2026-03-04 01:43:30 +03:00

Author

Owner

@gaul commented on GitHub (Jun 13, 2016):

Which version of s3fs do you use? I successfully created and mounted such a bucket with 1.80 via:

s3fs Gaul-_bucket $MOUNTPOINT -o createbucket -o use_path_request_style

@gaul commented on GitHub (Jun 13, 2016): Which version of s3fs do you use? I successfully created and mounted such a bucket with 1.80 via: ``` s3fs Gaul-_bucket $MOUNTPOINT -o createbucket -o use_path_request_style ```

kerem commented

2026-03-04 01:43:30 +03:00

Author

Owner

@nanodust commented on GitHub (Jun 13, 2016):

thanks Andrew. I'm fresh / latest :

Amazon Simple Storage Service File System V1.80(commit:36917f7) with OpenSSL

it only works when I don't have hyphens or underscores in my bucket name.

As I can't re-name the buckets (i need underscores & hyphens), I just moved over to aws cli sync, and gave up on fuse (which seemed the more elegant solution).

So this is just me then !? OK. I will close the issue.

@nanodust commented on GitHub (Jun 13, 2016): thanks Andrew. I'm fresh / latest : Amazon Simple Storage Service File System V1.80(commit:36917f7) with OpenSSL it only works when I don't have hyphens or underscores in my bucket name. As I can't re-name the buckets (i need underscores & hyphens), I just moved over to aws cli sync, and gave up on fuse (which seemed the more elegant solution). So this is just me then !? OK. I will close the issue.

kerem commented

2026-03-04 01:43:30 +03:00

Author

Owner

@r14c commented on GitHub (Aug 4, 2021):

I am seeing this issue on 1.89 when i try to mount a bucket using fstab.

[momo b2]# mount /mnt/b2/3Cvjjw-nexus/
s3fs: BUCKET /mnt/b2/3Cvjjw-nexus -- bucket name contains an illegal character.
[momo b2]# s3fs --version
Amazon Simple Storage Service File System V1.89 (commit:unknown) with OpenSSL
Copyright (C) 2010 Randy Rizun <rrizun@gmail.com>
License GPL2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

@r14c commented on GitHub (Aug 4, 2021): I am seeing this issue on 1.89 when i try to mount a bucket using fstab. ``` [momo b2]# mount /mnt/b2/3Cvjjw-nexus/ s3fs: BUCKET /mnt/b2/3Cvjjw-nexus -- bucket name contains an illegal character. [momo b2]# s3fs --version Amazon Simple Storage Service File System V1.89 (commit:unknown) with OpenSSL Copyright (C) 2010 Randy Rizun <rrizun@gmail.com> License GPL2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html> This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. ```

kerem commented

2026-03-04 01:43:31 +03:00

Author

Owner

@michaelwclark commented on GitHub (Aug 17, 2021):

I'm having this issue as well. Manually mounting or fstab

Amazon Simple Storage Service File System V1.84(commit:unknown) with GnuTLS(gcrypt)
Copyright (C) 2010 Randy Rizun <rrizun@gmail.com>
License GPL2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

@michaelwclark commented on GitHub (Aug 17, 2021): I'm having this issue as well. Manually mounting or fstab ``` Amazon Simple Storage Service File System V1.84(commit:unknown) with GnuTLS(gcrypt) Copyright (C) 2010 Randy Rizun <rrizun@gmail.com> License GPL2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html> This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. ```

kerem commented

2026-03-04 01:43:31 +03:00

Author

Owner

@DavidGarciaCat commented on GitHub (Sep 22, 2021):

Me too... this seems like a recurrent issue that should not be closed...

$ sudo vi /etc/fstab

s3fs#dgc-test /opt/test/dgc fuse.s3fs _netdev,allow_other,passwd_file=/etc/passwd-s3fs,default_acl=public-read,uid=1000,gid=1000 0 0

$ sudo mount -a

s3fs: BUCKET s3fs#dgc-test -- bucket name contains an illegal character.

$ s3fs --version

Amazon Simple Storage Service File System V1.86 (commit:unknown) with GnuTLS(gcrypt)
Copyright (C) 2010 Randy Rizun <rrizun@gmail.com>
License GPL2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

@DavidGarciaCat commented on GitHub (Sep 22, 2021): Me too... this seems like a recurrent issue that should not be closed... ``` $ sudo vi /etc/fstab s3fs#dgc-test /opt/test/dgc fuse.s3fs _netdev,allow_other,passwd_file=/etc/passwd-s3fs,default_acl=public-read,uid=1000,gid=1000 0 0 $ sudo mount -a s3fs: BUCKET s3fs#dgc-test -- bucket name contains an illegal character. $ s3fs --version Amazon Simple Storage Service File System V1.86 (commit:unknown) with GnuTLS(gcrypt) Copyright (C) 2010 Randy Rizun <rrizun@gmail.com> License GPL2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html> This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. ```

kerem commented

2026-03-04 01:43:31 +03:00

Author

Owner

@J1a-wei commented on GitHub (Mar 6, 2023):

same error in /etc/fstab

@J1a-wei commented on GitHub (Mar 6, 2023): same error in /etc/fstab

kerem commented

2026-03-04 01:43:31 +03:00

Author

Owner

@gaul commented on GitHub (Mar 6, 2023):

Please test with the latest version 1.91. We do not support older versions.

@gaul commented on GitHub (Mar 6, 2023): Please test with the latest version 1.91. We do not support older versions.

kerem commented

2026-03-04 01:43:31 +03:00

Author

Owner

@tve commented on GitHub (Jan 22, 2024):

Same here. I can mount a bucket that has a hyphen using the s3fs command but not via fstab. Version 1.92:

/s3> s3fs --version
Amazon Simple Storage Service File System V1.92 (commit:unknown) with OpenSSL
Copyright (C) 2010 Randy Rizun <rrizun@gmail.com>

E.g. this works:

/s3> sudo s3fs js-board /s3/js-board/ -f -d -o passwd_file=/etc/passwd-s3fs

And this doesn't:

/s3> sudo mount js-board
s3fs: BUCKET /s3/js-board -- bucket name contains an illegal character.

This is the fstab entry (wrapped for readability):

js-board /s3/js-board fuse.s3fs noatime,_netdev,nonempty,passwd_file=/etc/passwd-s3fs,\
default_acl=public-read,use_cache=/play/tmp/s3-cache,del_cache,\
url=https://s3.us-west-2.amazonaws.com,gid=1000,uid=1000,allow_other 0 0

@tve commented on GitHub (Jan 22, 2024): Same here. I can mount a bucket that has a hyphen using the `s3fs` command but not via fstab. Version 1.92: ``` /s3> s3fs --version Amazon Simple Storage Service File System V1.92 (commit:unknown) with OpenSSL Copyright (C) 2010 Randy Rizun <rrizun@gmail.com> ``` E.g. this works: ``` /s3> sudo s3fs js-board /s3/js-board/ -f -d -o passwd_file=/etc/passwd-s3fs ``` And this doesn't: ``` /s3> sudo mount js-board s3fs: BUCKET /s3/js-board -- bucket name contains an illegal character. ``` This is the fstab entry (wrapped for readability): ``` js-board /s3/js-board fuse.s3fs noatime,_netdev,nonempty,passwd_file=/etc/passwd-s3fs,\ default_acl=public-read,use_cache=/play/tmp/s3-cache,del_cache,\ url=https://s3.us-west-2.amazonaws.com,gid=1000,uid=1000,allow_other 0 0 ```

kerem commented

2026-03-04 01:43:31 +03:00

Author

Owner

@wrenchpilot commented on GitHub (Jan 24, 2024):

I was having this same issue, the documentation on what to put into /etc/fstab is not great. Here's what worked for me. Don't put anything before the bucket name.

BUCKETNAME /MOUNTPOINT fuse.s3fs _netdev,allow_other,passwd_file=/root/.passwd-s3fs 0 0

@wrenchpilot commented on GitHub (Jan 24, 2024): I was having this same issue, the documentation on what to put into /etc/fstab is not great. Here's what worked for me. **Don't put anything before the bucket name.** ```bash BUCKETNAME /MOUNTPOINT fuse.s3fs _netdev,allow_other,passwd_file=/root/.passwd-s3fs 0 0 ```

kerem commented

2026-03-04 01:43:31 +03:00

Author

Owner

@dMailonG commented on GitHub (May 28, 2024):

@gaul could you please reopen this issue?

@dMailonG commented on GitHub (May 28, 2024): @gaul could you please reopen this issue?

kerem commented

2026-03-04 01:43:31 +03:00

Author

Owner

@dMailonG commented on GitHub (May 28, 2024):

Just tested it, and it seems related to the bucket and the mount directory having the same name.
This is further reinforced by the error message exhibiting the full path to the mount directory as the bucket name.
It's interesting how when calling s3fs directly it works, but not through mount.

Bucket name: my-bucket
Directory: /media/mailon/my-bucket
Result: Fail (s3fs: BUCKET /media/mailon/my-bucket -- bucket name contains an illegal character.)

Bucket name: mybucket
Directory: /media/mailon/my-bucket
Result: Success

Bucket name: my-bucket
Directory: /media/mailon/mybucket
Result: Success

As per CheckForbiddenBucketParams() on s3fs_cred.cpp, dashes are not illegal characters, but slashes are:

    // check bucket name for illegal characters
    size_t found = bucket_name.find_first_of("/:\\;!@#$%^&*?|+=");
    if(found != std::string::npos){
        S3FS_PRN_EXIT("BUCKET %s -- bucket name contains an illegal character: '%c' at position %zu", bucket_name.c_str(), bucket_name[found], found);
        return false;
    }

I'd say the issue arises around my_fuse_opt_proc() on s3fs.cpp, but I'm unfamiliar with C++, so it's hard for me to tell.

// This is repeatedly called by the fuse option parser
// if the key is equal to FUSE_OPT_KEY_OPT, it's an option passed in prefixed by 
// '-' or '--' e.g.: -f -d -ousecache=/tmp
//
// if the key is equal to FUSE_OPT_KEY_NONOPT, it's either the bucket name 
//  or the mountpoint. The bucket name will always come before the mountpoint
//
static int my_fuse_opt_proc(void* data, const char* arg, int key, struct fuse_args* outargs)
{
    int ret;
    if(key == FUSE_OPT_KEY_NONOPT){
        // the first NONOPT option is the bucket name
        if(S3fsCred::GetBucket().empty()){
            if ((ret = set_bucket(arg))){
                return ret;
            }
            return 0;
        }else if (!strcmp(arg, "s3fs")) {
            return 0;
        }

        // the second NONOPT option is the mountpoint(not utility mode)
        if(mountpoint.empty() && utility_incomp_type::NO_UTILITY_MODE == utility_mode){
            // save the mountpoint and do some basic error checking
            mountpoint = arg;
            struct stat stbuf;

@dMailonG commented on GitHub (May 28, 2024): Just tested it, and it seems related to the bucket and the mount directory having the same name. This is further reinforced by the error message exhibiting the full path to the mount directory as the bucket name. It's interesting how when calling **s3fs** directly it works, but not through **mount**. Bucket name: my-bucket Directory: /media/mailon/my-bucket Result: Fail (s3fs: BUCKET /media/mailon/my-bucket -- bucket name contains an illegal character.) Bucket name: mybucket Directory: /media/mailon/my-bucket Result: Success Bucket name: my-bucket Directory: /media/mailon/mybucket Result: Success As per **CheckForbiddenBucketParams()** on **s3fs_cred.cpp**, dashes are not illegal characters, but slashes are: ``` // check bucket name for illegal characters size_t found = bucket_name.find_first_of("/:\\;!@#$%^&*?|+="); if(found != std::string::npos){ S3FS_PRN_EXIT("BUCKET %s -- bucket name contains an illegal character: '%c' at position %zu", bucket_name.c_str(), bucket_name[found], found); return false; } ``` I'd say the issue arises around **my_fuse_opt_proc()** on **s3fs.cpp**, but I'm unfamiliar with C++, so it's hard for me to tell. ``` // This is repeatedly called by the fuse option parser // if the key is equal to FUSE_OPT_KEY_OPT, it's an option passed in prefixed by // '-' or '--' e.g.: -f -d -ousecache=/tmp // // if the key is equal to FUSE_OPT_KEY_NONOPT, it's either the bucket name // or the mountpoint. The bucket name will always come before the mountpoint // static int my_fuse_opt_proc(void* data, const char* arg, int key, struct fuse_args* outargs) { int ret; if(key == FUSE_OPT_KEY_NONOPT){ // the first NONOPT option is the bucket name if(S3fsCred::GetBucket().empty()){ if ((ret = set_bucket(arg))){ return ret; } return 0; }else if (!strcmp(arg, "s3fs")) { return 0; } // the second NONOPT option is the mountpoint(not utility mode) if(mountpoint.empty() && utility_incomp_type::NO_UTILITY_MODE == utility_mode){ // save the mountpoint and do some basic error checking mountpoint = arg; struct stat stbuf; ```

kerem commented

2026-03-04 01:43:31 +03:00

Author

Owner

@DavidGarciaCat commented on GitHub (Aug 8, 2024):

Hello @gaul

I was wondering if you or one of your colleagues maintaining s3fs-fuse have had a chance to review @dMailonG's previous post (written about 2.5 months ago), as it seems to identify an existing issue in one of the cpp files.

Thanks,

@DavidGarciaCat commented on GitHub (Aug 8, 2024): Hello @gaul I was wondering if you or one of your colleagues maintaining `s3fs-fuse` have had a chance to review @dMailonG's previous post (written about 2.5 months ago), as it seems to identify an existing issue in one of the `cpp` files. Thanks,

kerem commented

2026-03-04 01:43:31 +03:00

Author

Owner

@ggtakec commented on GitHub (Aug 11, 2024):

@DavidGarciaCat @dMailonG
I tried this with the current master branch code, but I can't reproduce it.

I tried the path style case and the other case, and both were mounted without any problems.
The fstab entry I tried is the following:

(1) my-bucket /mnt/my-bucket fuse.s3fs _netdev,allow_other,passwd_file=/etc/passwd-s3fs 0 0
(2) my-bucket /mnt/my-bucket fuse.s3fs _netdev,allow_other,passwd_file=/etc/passwd-s3fs,url=https://s3-ap-northeast-1.amazonaws.com 0 0

If you are still having trouble with this problem, specify the dbglevel and curldbg options as follows to have s3fs output debug logs.
These debug logs are output to files under /var/log, etc. (If you don't know the log file, please refer to the logfile option.)

my-bucket /mnt/my-bucket fuse.s3fs _netdev,allow_other,passwd_file=/etc/passwd-s3fs,dbglevel=dbg,curldbg 0 0

Then, if the problem persists, please post a new issue with that information(debug logs, etc.).

Thanks in advance for your assistance.

@ggtakec commented on GitHub (Aug 11, 2024): @DavidGarciaCat @dMailonG I tried this with the current master branch code, but I can't reproduce it. I tried the path style case and the other case, and both were mounted without any problems. The fstab entry I tried is the following: ``` (1) my-bucket /mnt/my-bucket fuse.s3fs _netdev,allow_other,passwd_file=/etc/passwd-s3fs 0 0 (2) my-bucket /mnt/my-bucket fuse.s3fs _netdev,allow_other,passwd_file=/etc/passwd-s3fs,url=https://s3-ap-northeast-1.amazonaws.com 0 0 ``` If you are still having trouble with this problem, specify the `dbglevel` and `curldbg` options as follows to have s3fs output debug logs. These debug logs are output to files under `/var/log`, etc. (If you don't know the log file, please refer to the `logfile` option.) ``` my-bucket /mnt/my-bucket fuse.s3fs _netdev,allow_other,passwd_file=/etc/passwd-s3fs,dbglevel=dbg,curldbg 0 0 ``` Then, if the problem persists, please post a new issue with that information(debug logs, etc.). Thanks in advance for your assistance.

kerem commented

2026-03-04 01:43:31 +03:00

Author

Owner

@kallisti5 commented on GitHub (May 21, 2025):

ps: any further lurkers... this one has to do with your current working directory. If you move out of the path where the fuse mount happens, the error goes away

Conditions:

/etc/fstab (example mounting to: /s3/blah-thing)
your pwd is /s3
you mount -a

In the conditions above, you get "bucket name contains an illegal character"

@kallisti5 commented on GitHub (May 21, 2025): ps: any further lurkers... this one has to do with your current working directory. If you move out of the path where the fuse mount happens, the error goes away Conditions: * /etc/fstab (example mounting to: /s3/blah-thing) * your pwd is /s3 * you ```mount -a``` In the conditions above, you get "bucket name contains an illegal character"

kerem referenced this issue

2026-03-04 01:53:48 +03:00

[PR #232] [MERGED] Always hold stat_cache_lock when using stat_cache #1410

Rows
Columns

[GH-ISSUE #434] S3 Bucket Naming Limitations #232