firebase / firebase/extensions

docs(storage-resize-images): document FUNCTION_DEFAULT_REGION matching Storage bucket region during migration to Function Kit

Open
#3,159 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
979
Forks
433
Avg merge
1d 22h
Merged PRs (30d)
127

Description

### Summary

When users migrate from 1st Gen Firebase Extensions to 2nd Gen Function Kits using `firebase ext:migrate`, deployments may fail with a region validation error if the exported `FUNCTION_DEFAULT_REGION` parameter does not match the underlying resource's location (such as Cloud Storage buckets, regional Cloud Firestore databases, or Realtime Database instances).

Because 1st Gen Extensions allowed cross-region event triggers in many configurations, many projects have their extension functions deployed in `us-central1` (the default prompt option) while their Storage bucket or database was provisioned in another region (e.g., `us-east1`, `europe-west1`, `asia-east1`).

2nd Gen Cloud Functions (Eventarc triggers) strictly enforce that event-triggered functions must be deployed in the same region as their underlying data resource. During `firebase ext:migrate`, the legacy `LOCATION` parameter (typically `us-central1`) is exported to `FUNCTION_DEFAULT_REGION` in `.env.`. For projects where the resource is located in a different region, this causes the initial post-migration deployment to fail during pre-deploy validation:

```text
FirebaseError: A function in region us-central1 cannot listen to a bucket in region
Error: Failed to deploy. Please fix and retry with firebase deploy --only functions:
```

---

### Scope Across the 13 Official Function Kits

We would like to request adding a standard **"Migration Troubleshooting: Trigger Region Mismatch"** section to the READMEs of the event-triggered Function Kits across this repository:

1. **Cloud Storage Triggers**:
- `storage-resize-images`
- `speech-to-text`
2. **Cloud Firestore Triggers**:
- `firestore-bigquery-export`
- `firestore-send-email`
- `firestore-translate-text`
- `firestore-counter`
- `firestore-genai-chatbot`
- `firestore-vector-search`
- `firestore-incremental-capture`
3. **Realtime Database Triggers**:
- `rtdb-limit-child-nodes`

*(Note: Kits that only use HTTP endpoints, Task Queues, or Scheduled crons — such as `bigquery-firestore-export`, `delete-user-data`, and `firestore-bundle-builder` — are not bound to a specific regional data resource and do not encounter this validation error).*

---

### Proposed Standard README Troubleshooting Section

Below is the standardized section to include in the README of each affected Function Kit:

#### Migrating from 1st Gen Extension: Trigger Region Mismatch

If your 1st Gen extension was deployed in `us-central1` but your resource (Storage bucket, Firestore database, or RTDB instance) is located in another region (e.g., `us-east1`, `europe-west1`), 2nd Gen Cloud Functions require the function region to match the resource's location.

##### How to Resolve:

1. **Find your resource region**:
* **Cloud Storage Buckets**:
* *Firebase Console*: Go to **Build > Storage** and view the location next to your bucket name.
* *CLI*: `gcloud storage buckets describe gs:// --project --format="value(location)"`
* **Cloud Firestore Databases**:
* *Firebase Console*: Go to **Build > Firestore Database** and view the database location.
* *CLI*: `gcloud firestore databases describe --project --format="value(locationId)"`
* **Realtime Database**:
* *Firebase Console*: Go to **Build > Realtime Database** and view the database location.
* *CLI*: `firebase database:instances:list --project --json`

2. **Update your `.env` configuration**:
Open `function-kits//config-/.env.` and update `FUNCTION_DEFAULT_REGION` to match your resource location (in lowercase, e.g. `us-east1` or `europe-west1`):
```properties
FUNCTION_DEFAULT_REGION=us-east1
```

3. **Deploy the Function Kit**:
```bash
firebase deploy --only functions: --project
```

4. **Uninstall the legacy extension once verified**:
```bash
firebase ext:uninstall --project --immediate
```

Contributor guide

Open the contributing guide

Research direction

Start by locating the README files for the listed event-triggered Function Kits, including storage-resize-images, speech-to-text, the Firestore kits, and rtdb-limit-child-nodes. Add the proposed migration troubleshooting section consistently to each affected README, then verify that the region lookup, .env update, deployment, and legacy-extension removal commands are documented accurately.

Written by the indexing model from the issue text.

Assessment

Tech stack
firebase, google-cloud
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
66/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.