Cloudflare Deploy

wrangler d1 execute 中の SQLITE_BUSY

症状:

Error: D1_ERROR: database is locked at line 1: ...

原因: wrangler dev が同じローカル D1 ファイルに対して動いていて、 排他ロックを保持しています。別のプロセスがロックを持っている間、 wrangler d1 execute は書き込みハンドルを取得できません。

対処:

1. まず wrangler dev を停止し、wrangler d1 execute を実行してから、 再度 wrangler dev を起動する。
2. または wrangler dev --persist-to ./.wrangler/dev で dev サーバーに 別の state ディレクトリを与え、wrangler d1 execute --persist-to ./.wrangler/exec を別のディレクトリに対して実行して、両者が state を共有しないようにする。

注意

--persist-to を分けると、wrangler d1 execute の書き込みは wrangler dev が 読む DB とは別の DB に着地します。「DB を帯域外で mutate したらどうなるか」を 積極的にテストしているときだけ使ってください。

本番で D1 binding not found

症状:

TypeError: Cannot read property 'prepare' of undefined
   at fromD1

原因: wrangler.jsonc に、Env で使っている名前と一致する d1_databases binding がありません。

対処:

{
  "d1_databases": [
    {
      "binding": "DB",           // ← this must match env.DB
      "database_name": "my-app-prod",
      "database_id": "<from wrangler d1 create output>"
    }
  ]
}

その後、再デプロイします。

pnpm wrangler deploy

binding 文字列は、Worker 内の env に現れるものです。コードで env.MY_DB と 書くなら、binding は "MY_DB" でなければなりません。

R2 binding not found

症状:

TypeError: Cannot read property 'put' of undefined
   at r2Storage.upload

D1 と同じ原因・対処パターンです。

{
  "r2_buckets": [
    {
      "binding": "BUCKET",
      "bucket_name": "my-app-blobs"
    }
  ]
}

まだバケットを作成していなければ作成します。

pnpm wrangler r2 bucket create my-app-blobs

wrangler tail に何も出ない

症状: push リクエストを発行しているのに wrangler tail に出力が出ません。

よくある原因:

• 環境が違う。 wrangler tail my-app はデプロイ済みの Worker を tail します。 ローカルの wrangler dev は独自のコンソール出力を持ちます。ローカルでテスト しているなら、wrangler dev を動かしているターミナルを確認してください。
• Observability が無効。 wrangler.jsonc に "observability": { "enabled": true } を追加して再デプロイしてください。
• リクエストがキャッシュに当たっている。 /sync/pull の前面に Cloudflare の キャッシュルールがあると、キャッシュされたレスポンスは Worker を完全に スキップします。実際にはまれです — plasma の pull レスポンスはキャッシュに 適さないはずです (呼び出しごとに異なる cookie パラメータを持つため)。

Durable Object の migration に失敗

症状:

Error: Durable Object namespace not defined: SyncCoordinator

原因: wrangler.jsonc は DO binding を宣言しているのに、migration タグが 適用されていません。

対処:

{
  "durable_objects": {
    "bindings": [
      { "name": "COORDINATOR", "class_name": "SyncCoordinator" }
    ]
  },
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": ["SyncCoordinator"]
    }
  ]
}

その後:

pnpm wrangler deploy

migrations[].tag は文字列の識別子です。DO クラスの構造を変更するたびに 上げてください (v2、v3)。

wrangler deploy は成功するがリクエストが 404

症状: デプロイは完了するのに、 curl https://my-app.<subdomain>.workers.dev/sync/push が 404 を返す。

原因:

• ルートがない。 カスタムドメインのデプロイには、Cloudflare ダッシュボードで 定義されたルートが必要です。それがないと、Worker は .workers.dev でしか 到達できません。
• worker 名が違う。 wrangler.jsonc の name フィールドがサブドメインの パスと一致しているか確認してください。
• main が間違ったファイルを指している。 "main": "./worker.ts" は、 デフォルトの fetch ハンドラを export するファイルと一致しなければなりません。

nodejs_compat が欠けている

症状:

TypeError: node:crypto: not implemented

原因: plasma は crypto.subtle (利用可能) を使いますが、一部のコードパスが 依存関係を介して間接的に node:crypto に手を伸ばします。

対処:

{
  "compatibility_flags": ["nodejs_compat"]
}

環境変数が見えない

症状: 実行時に env.MY_VAR が undefined。

対処:

非シークレットの変数は wrangler.jsonc で宣言します。

{
  "vars": {
    "MY_VAR": "value"
  }
}

シークレットの場合:

pnpm wrangler secret put MY_VAR

どちらも実行時に env に現れます。TypeScript には手動の宣言が必要です。

interface Env {
  DB: D1Database
  BUCKET: R2Bucket
  MY_VAR: string
  MY_SECRET: string
}

次に読むもの

• デプロイ — 本番配線の全体
• Migrations — デプロイ時の DDL ステップ