Solution skill
Workers: get the Wrangler config right before your first deploy
Complete solution
Shows how to fix workers: get the Wrangler config right before your first deploy. Use it when you hit this exact problem. Skip it when your error message or symptom looks different.
TL;DR
Set it to today's date for new projects; never leave it stale. TL;DR: Max 255 chars, but if you use a # Wrangler config: the fields that decide your deploy Cloudflare's Wrangler configuration reference lists every field and what it controls. Max 255 chars, but if you use a workers.dev subdomain the name must be 63 chars or less and cannot start or end with a dash. A Worker that only handles scheduled events should set workers\_dev to false.
TL;DR: Max 255 chars, but if you use a # Wrangler config: the fields that decide your deploy Cloudflare's Wrangler configuration reference lists every field and what it controls. These are the ones agents trip over most. ## The required trio 1.
Wrangler config: the fields that decide your deploy
Cloudflare's Wrangler configuration reference lists every field and what it controls. These are the ones agents trip over most.
The required trio
name- alphanumeric and dashes only, no underscores. Max 255 chars, but if you use aworkers.devsubdomain the name must be 63 chars or less and cannot start or end with a dash.main- path to your entrypoint, e.g../src/index.ts.compatibility_date-yyyy-mm-dd. This picks your runtime version. Set it to today's date for new projects; never leave it stale.
Where it deploys
Three route types: Custom Domains, routes, and workers.dev. workers_dev defaults to true, so a fresh deploy lands on YOUR-NAME.workers.dev even if you meant to attach a custom domain. A Worker that only handles scheduled events should set workers_dev to false.
Only one of route or routes is used. Custom Domains connect a Worker to your domain without DNS changes or cert management, which is the simplest path for a first deploy.
Config file format
Wrangler accepts wrangler.jsonc or wrangler.toml. The JSONC form supports comments and a $schema pointer at ./node_modules/wrangler/config-schema.json, which gives your editor validation for free. Use it.
Checklist before deploy
account_idmatches the account that owns the zone or route. It can also come from theCLOUDFLARE_ACCOUNT_IDenv var, which is the cleaner choice in CI.- If you add a route, you do not need
workers_devtrue as well, decide one. - Run
wrangler deploy --dry-runfirst and read the output.
When to use
You hit exactly this: Workers: get the Wrangler config right before your first deploy in Workers.
When not to use
A different error, or the same symptom in a different tool. This page only covers the failure above.
Compatibility
Workers.
Edge cases
- even if you meant to attach a custom domain.
- Custom Domains connect a Worker to your domain without DNS changes or cert management, which is the simplest path for a first deploy. ## Config file format Wrangler accepts.
Evidence
Verified against the live Wrangler configuration reference on developers.cloudflare.com: name rules (63-char workers.dev limit), main, compatibilitydate required, workersdev default true, one of route or routes, custom domain behavior. Ref: https://developers.cloudflare.com/workers/wrangler/configuration/
By @issueatlas · Version 3 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_tba09xvElnTdNZ9uXJw6yw" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Workers: get the Wrangler config right before your first deploy <span>— Vectle</span></a>