juicedata/juicefs · error

GOOGLE_CLOUD_PROJECT environment variable must be set

Error message

GOOGLE_CLOUD_PROJECT environment variable must be set

What it means

Creating a new GCS bucket (gsStore.Create) needs a project ID; when it was not supplied in the URL/config and default credentials carry no project, the code requires the GOOGLE_CLOUD_PROJECT environment variable and errors otherwise.

Source

Thrown at pkg/object/gs.go:79

}

func (g *gs) Create(ctx context.Context) error {
	// check if the bucket is already exists
	if objs, _, _, err := g.List(ctx, "", "", "", "", 1, true); err == nil && len(objs) > 0 {
		return nil
	}
	projectID := os.Getenv("GOOGLE_CLOUD_PROJECT")
	if projectID == "" {
		projectID, _ = metadata.ProjectIDWithContext(ctx)
	}
	if projectID == "" {
		cred, err := google.FindDefaultCredentials(ctx)
		if err == nil {
			projectID = cred.ProjectID
		}
	}
	if projectID == "" {
		return errors.New("GOOGLE_CLOUD_PROJECT environment variable must be set")
	}
	// Guess region when region is not provided
	if g.region == "" {
		zone, err := metadata.ZoneWithContext(ctx)
		if err == nil && len(zone) > 2 {
			g.region = zone[:len(zone)-2]
		}
	}

	err := g.getClient().Bucket(g.bucket).Create(ctx, projectID, &storage.BucketAttrs{
		Name:         g.bucket,
		StorageClass: g.tiers[0].Sc,
		Location:     g.region,
	})
	if err != nil && strings.Contains(err.Error(), "You already own this bucket") {
		return nil
	}
	return err

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Export GOOGLE_CLOUD_PROJECT=<your-gcp-project-id> before running the command.
2. Append the project to the bucket URL, e.g. gs://mybucket?project=my-project (or pass region/project in the format options).
3. Use credentials whose JSON includes project_id (re-download the service account key), so FindDefaultCredentials resolves it.
4. Fix the env var name spelling and ensure it is exported in the sudo/CI environment.

Example fix

// before
juicefs format "gs://mybucket" myjfs
// after
export GOOGLE_CLOUD_PROJECT=my-gcp-project
juicefs format "gs://mybucket" myjfs

if os.Getenv("GOOGLE_CLOUD_PROJECT") == "" && !strings.Contains(bucketURL, "project=") {
    return fmt.Errorf("set GOOGLE_CLOUD_PROJECT or add ?project=<id> to the gs:// URL")
}

if _, err := object.CreateStorage(ctx, "gs", "bucket", "", ""); err != nil {
    if strings.Contains(err.Error(), "GOOGLE_CLOUD_PROJECT") {
        return fmt.Errorf("GCS project missing: export GOOGLE_CLOUD_PROJECT or use gs://bucket?project=ID")
    }
    return err
}

When it happens

Trigger: Running juicefs format (bucket creation) against gs:// without ?project= in the bucket URL, when the service account/ADC credentials have no project_id field (e.g. a raw JSON key without it, or metadata server unavailable).

Common situations: CI machines with GOOGLE_APPLICATION_CREDENTIALS set to a key file lacking project_id; on-prem/VMs outside GCP where the metadata zone lookup fails; typos like GOOGLE_CLOUND_PROJECT.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Invalid endpoint: %v, error: %v
• ceph: can't put empty file
• passphrase is required to private key
• object key cannot be empty
• not exists

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/4bda653655d12565. Report an issue: GitHub.