Deployment issues

#Local dev returns 500: "Cannot read properties of undefined (reading 'replace')"

#Problem

The Worker crashes in local development with a 500 error and Cannot read properties of undefined (reading 'replace') (or a similar "reading property of undefined" message). wrangler dev lists secrets such as BETTER_AUTH_SECRET as missing, even though you set them with wrangler secret put.

#Cause

Secrets uploaded with wrangler secret put exist only in your deployed Cloudflare environment — wrangler dev doesn't download them. For local development, secrets must live in a .dev.vars file at the worker root (next to wrangler.toml), which wrangler dev reads automatically. Without it, the env vars are undefined and any code that reads them fails.

#Fix

1. Create workers/gateway/.dev.vars with the secrets the worker needs:

   BETTER_AUTH_SECRET=a-long-random-string
   BETTER_AUTH_URL=http://localhost:8787
   

2. Restart wrangler dev — the file is only read at startup.

#Prevention

Create a .dev.vars file whenever you add a worker that uses secrets. The file is gitignored — never commit real secret values.

#Databases stop working after a deploy

#Problem

Collections stored in a dynamically provisioned database return errors after you run wrangler deploy, even though they worked before. The Settings → Databases page may show a warning banner about at-risk bindings before this happens.

#Cause

The static deployment template only declares the D1 bindings DB_POOL_0 through DB_POOL_4. When EmuView provisions a database dynamically, it attaches it under a higher binding (DB_POOL_5 and up) at runtime — but that binding isn't in wrangler.template.toml. The next wrangler deploy regenerates the Worker's bindings from the template, silently dropping the dynamic ones.

#Fix

1. Check GET /api/v1/databases/provision-status (or the Settings → Databases page). The atRiskBindings list names every dynamically provisioned binding that isn't declared in the template. This is an operator view: it scans every workspace on the deployment, so it needs system/tenants:read — super admin only — and a workspace admin gets a 403 (the banner simply doesn't appear for them).
2. Add each at-risk binding to wrangler.template.toml as a [[d1_databases]] entry with its binding key and database id.
3. Redeploy.

#Prevention

Treat the warning banner on Settings → Databases as a pre-deploy checklist item: whenever it appears, update the template before the next deploy. Only a super admin sees it, so make the check part of the deploy routine rather than expecting a workspace admin to report it. EmuView can detect the drift but can't write to your repository, so the template edit is always manual.

#Run Script fails: "Script execution unavailable: no isolated sandbox tier is configured"

#Problem

An automation flow's Run Script step fails with Script execution unavailable: no isolated sandbox tier is configured. Contact your administrator. The flow's logs show that full JS execution was refused.

#Cause

Script execution requires the SCRIPT_LOADER binding (Cloudflare Dynamic Workers / worker_loaders), which runs user scripts in a separate V8 isolate with no access to the gateway's bindings or secrets. If the binding isn't configured, EmuView refuses to run scripts in every environment — including local dev — rather than falling back to an unsafe in-process sandbox.

#Fix

1. Add the SCRIPT_LOADER worker_loaders binding to your gateway wrangler.toml and redeploy.
2. If you can't enable Dynamic Workers, use the Run Expression operation (JSONata) instead — it covers most data-transformation needs without full JS execution.

#Prevention

Keep the SCRIPT_LOADER binding from the deployment template in place if your flows use Run Script. Prefer Run Expression for pure data transformation — it has no infrastructure requirement.

#A deploy broke your instance and you need to roll back

#Problem

An instance stops working after an update and you need to restore the previous Worker version quickly.

#Cause

A newly deployed Worker version has a bug or a configuration problem. Cloudflare keeps previous Worker versions, so the update tooling can roll the instance back to the version that was live before the deploy.

#Fix

1. Every successful update prints the exact rollback command in its footer, including the previous version id. Run it:

   node scripts/update.mjs --name my-app --rollback --to <version-id>
   

2. Without --to, the script looks up and auto-selects the previous version:

   node scripts/update.mjs --name my-app --rollback
   

3. Rollback requires --name — instances are rolled back one at a time, never with --all.

#Prevention

Back up your D1 database before upgrading, and keep the rollback command printed by each update until you've confirmed the deploy is healthy. See upgrades for the full upgrade checklist.