http://starrocks.io logo
Join Slack
Powered by
<@U0A71G31CDV> on enabling cluster snapshot, getti...
# questions-and-troubleshooting
m
@Rocky on enabling cluster snapshot, getting this error
Copy code
2026-08-10 16:39:01.624+05:30 WARN (starrocks-mysql-nio-pool-6304|2493754) [FileSystem.createFileSystemInternal():3749] Failed to initialize filesystem gs://<bucket>/data/92260329-957f-4d5f-932d-29def789f8d7/meta/image/automated_cluster_snapshot_1786360074856: java.lang.NullPointerException
	2026-08-10 16:39:01.874	
Caused by: java.lang.NullPointerException
	2026-08-10 16:39:01.874	
 com.starrocks.common.StarRocksException: java.lang.NullPointerException
✅ 1
r
The error 
java.lang.NullPointerException
at 
FileSystem.createFileSystemInternal()
during the initialization of a 
gs://
path typically occurs due to a configuration mismatch between the Storage Volume Type and the Location URI scheme, or missing mandatory credential properties. Here are the most common causes and solutions: 1. Scheme and Type Mismatch In StarRocks, there are two ways to connect to Google Cloud Storage (GCS). Using the wrong combination often leads to initialization errors: * S3-Compatible Mode (Recommended for Shared-Data/Snapshots): * Type: 
S3
* Location: Must use 
s3://
prefix (e.g., `s3://your-bucket/path`). * Reason: StarRocks uses the GCS XML API (S3-compatible). If you use 
gs://
with 
TYPE = S3
, the filesystem initialization may fail with an NPE because it expects S3-specific configurations that aren't properly mapped for a 
gs://
URI. * Native GCS Mode (Supported from v3.5.1+): * Type: 
GS
* Location: Uses 
gs://
prefix. * Note: This requires native GCS credentials (Service Account email/key). Solution: Check your storage volume definition (or 
fe.conf
if using the built-in volume). If you are using GCS via the S3-compatible API, ensure the location starts with 
s3://
.
Copy code
sql
-- Example for GCS using S3-compatible API
CREATE STORAGE VOLUME gcs_volume
TYPE = S3
LOCATIONS = ("<s3://your-bucket-name>") -- Use s3:// even for GCS
PROPERTIES (
    "aws.s3.endpoint" = "<https://storage.googleapis.com>",
    "aws.s3.region" = "auto", -- or your specific region
    "aws.s3.access_key" = "YOUR_HMAC_ACCESS_KEY",
    "aws.s3.secret_key" = "YOUR_HMAC_SECRET_KEY"
);
2. Missing Mandatory Credentials If you are using 
TYPE = GS
(Native GCS), the NPE can occur if required properties like 
gcp.gcs.service_account_email
or 
gcp.gcs.service_account_private_key
are null or missing from the properties map. Solution: Ensure all required GCS properties are provided. For Service Account authentication:
Copy code
sql
CREATE STORAGE VOLUME gcs_native
TYPE = GS
LOCATIONS = ("<gs://your-bucket-name>")
PROPERTIES (
    "gcp.gcs.use_compute_engine_service_account" = "false",
    "gcp.gcs.service_account_email" = "<mailto:your-sa@project.iam.gserviceaccount.com|your-sa@project.iam.gserviceaccount.com>",
    "gcp.gcs.service_account_private_key_id" = "...",
    "gcp.gcs.service_account_private_key" = "..."
);
3. Version Compatibility * Cluster Snapshot for shared-data clusters was introduced as a beta feature in v3.4.2. * Native GCS support (
TYPE = GS
) for storage volumes was introduced in v3.5.1. If you are on a version between v3.4.2 and v3.5.0, you must use 
TYPE = S3
with the 
s3://
scheme to store cluster snapshots in GCS. Using 
gs://
in these versions will likely result in the error you see. Summary Checklist: 1. Run 
SHOW STORAGE VOLUMES;
and 
DESC STORAGE VOLUME <name>;
to verify the 
TYPE
and 
LOCATIONS
. 2. If the location is 
gs://<bucket>
, ensure the 
TYPE
is 
GS
and you are on StarRocks v3.5.1 or later. 3. If you are using the S3-compatible API, change the location prefix from 
gs://
to 
s3://
. 4. Verify that no mandatory credential keys are empty or missing in your 
PROPERTIES
. If the issue persists, check if you have set 
aws_s3_path
in your 
fe.conf
with a 
gs://
prefix, which should be removed or changed to 
s3://
for S3-mode.0. References • administration/cluster_snapshot.md • deployment/shared_data/gcs.md
m
@Rocky I'm using TYPE=GS with required params only
Copy code
CREATE STORAGE VOLUME nob_starrocks_dev
TYPE = GS
LOCATIONS = ("gs://<bucket>")
PROPERTIES
(
    "enabled" = "true",
    "gcp.gcs.use_compute_engine_service_account" ="false",
...
)
r
The 
java.lang.NullPointerException
at 
FileSystem.createFileSystemInternal()
during cluster snapshot initialization usually indicates a StarRocks version incompatibility or missing mandatory credential properties for the 
GS
storage type. 1. Check StarRocks Version Native Google Cloud Storage support (
TYPE = GS
and 
gs://
scheme) was introduced in v3.5.1. * If you are on v3.5.0 or older: 
TYPE = GS
is not supported. You must use S3-compatible mode: * Set 
TYPE = S3
. * Use the 
s3://
prefix in 
LOCATIONS
. * Provide S3-style HMAC keys (Access/Secret). * If you are on v3.5.1+: Native 
GS
is supported, but the feature is relatively new and might have edge cases with the Cluster Snapshot component. 2. Verify Mandatory Properties When you set 
"gcp.gcs.use_compute_engine_service_account" = "false"
, StarRocks expects specific service account credentials. If any are missing or null, the filesystem initialization will fail with an NPE. Ensure your 
CREATE STORAGE VOLUME
includes all of the following:
Copy code
sql
PROPERTIES
(
    "enabled" = "true",
    "gcp.gcs.use_compute_engine_service_account" = "false",
    -- All three below are mandatory for SA-based auth:
    "gcp.gcs.service_account_email" = "<mailto:your-sa@project.iam.gserviceaccount.com|your-sa@project.iam.gserviceaccount.com>",
    "gcp.gcs.service_account_private_key_id" = "your-key-id",
    "gcp.gcs.service_account_private_key" = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
)
3. Snapshot Compatibility Workaround Cluster Snapshot is a beta feature (introduced in v3.4.2) that was originally built around the 
S3
and 
HDFS
filesystem implementations. If you are on v3.5.1+ and the properties above are correct, there may be a bug in how the snapshot component handles the 
GS
native filesystem. Recommended Workaround: Use the GCS XML API (S3-compatible). This is the most stable way to handle GCS for snapshots across all versions: 1. Generate HMAC keys in the GCS Console (Settings > Interoperability). 2. Create the Storage Volume using `TYPE = S3`:
Copy code
sql
    CREATE STORAGE VOLUME gcs_s3_snapshot
    TYPE = S3
    LOCATIONS = ("s3://<your-bucket>") -- Use s3:// prefix
    PROPERTIES (
        "enabled" = "true",
        "aws.s3.endpoint" = "<https://storage.googleapis.com>",
        "aws.s3.region" = "auto", -- or your bucket region
        "aws.s3.access_key" = "GOOG...",
        "aws.s3.secret_key" = "..."
    );
3. Enable Snapshots on this volume:
Copy code
sql
    ADMIN SET AUTOMATED CLUSTER SNAPSHOT ON STORAGE VOLUME gcs_s3_snapshot;
4. Check for Empty Path Style If you are using the built-in volume or configured GCS via 
fe.conf
, ensure the 
aws_s3_path
does not include the 
gs://
scheme (it should just be 
bucket/path
) and that the 
cloud_native_storage_type
matches the credential type you've provided. If you continue to see this error on v3.5.1+ with all properties set, it is likely a bug in the native 
GS
filesystem registration for snapshots. I recommend reporting this in the StarRocks community Slack with your exact version number-your exact version number. References • administration/cluster_snapshot.md
5 Views
Open in Slack
PreviousNext
Powered by