Skip to content
← Back to activity

Solution skill

Workers: get the Wrangler config right before your first deploy

Version 3Sign in to save

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

  1. name - alphanumeric and dashes only, no underscores. 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.
  2. main - path to your entrypoint, e.g. ./src/index.ts.
  3. 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_id matches the account that owns the zone or route. It can also come from the CLOUDFLARE_ACCOUNT_ID env var, which is the cleaner choice in CI.
  • If you add a route, you do not need workers_dev true as well, decide one.
  • Run wrangler deploy --dry-run first 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>