AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

cloudflare-deploy

Deploy applications and infrastructure to Cloudflare using Workers, Pages, and related platform services. Use when the user asks to deploy, host, publish, or set up a project on Cloudflare.

Original source
openai
License
Apache-2.0
Pinned revision
49f948faa9258a0c61caceaf225e179651397431

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read openai--cloudflare-deploy at revision 49f948faa9258a0c61caceaf225e179651397431, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 309

references/tail-workers/gotchas.md

Tail Workers Gotchas & Debugging

Critical Pitfalls

1. Not Using ctx.waitUntil()

Problem: Async work doesn't complete or tail Worker times out
Cause: Handlers exit immediately; awaiting blocks processing
Solution:

// ❌ WRONG - fire and forget
export default {
  async tail(events) {
    fetch(endpoint, { body: JSON.stringify(events) });
  }
};

// ❌ WRONG - blocking await
export default {
  async tail(events, env, ctx) {
    await fetch(endpoint, { body: JSON.stringify(events) });
  }
};

// ✅ CORRECT
export default {
  async tail(events, env, ctx) {
    ctx.waitUntil(
      (async () => {
        await fetch(endpoint, { body: JSON.stringify(events) });
        await processMore();
      })()
    );
  }
};

2. Missing tail() Handler

Problem: Producer deployment fails
Cause: Worker in tail_consumers doesn't export tail() handler
Solution: Ensure export default { async tail(events, env, ctx) { ... } }

3. Outcome vs HTTP Status

Problem: Filtering by wrong status
Cause: outcome is script execution status, not HTTP status

// ❌ WRONG
if (event.outcome === 500) { /* never matches */ }

// ✅ CORRECT
if (event.outcome === 'exception') { /* script threw */ }
if (event.event?.response?.status === 500) { /* HTTP 500 */ }

4. Timestamp Units

Problem: Dates off by 1000x
Cause: Timestamps are epoch milliseconds, not seconds

// ❌ WRONG: const date = new Date(event.eventTimestamp * 1000);
// ✅ CORRECT: const date = new Date(event.eventTimestamp);

5. Type Name Mismatch

Problem: Using TailItem type
Cause: Old docs used TailItem, SDK uses TraceItem

import type { TraceItem } from '@cloudflare/workers-types';
export default {
  async tail(events: TraceItem[], env, ctx) { /* ... */ }
};

6. Excessive Logging Volume

Problem: Unexpected high costs
Cause: Invoked on EVERY producer request
Solution: Sample events

export default {
  async tail(events, env, ctx) {
    if (Math.random() > 0.1) return;  // 10% sample
    ctx.waitUntil(sendToEndpoint(events));
  }
};

7. Serialization Issues

Problem: JSON.stringify() fails
Cause: log.message is unknown[] with non-serializable values
Solution:

const safePayload = events.map(e => ({
  ...e,
  logs: e.logs.map(log => ({
    ...log,
    message: log.message.map(m => {
      try { return JSON.parse(JSON.stringify(m)); }
      catch { return String(m); }
    })
  }))
}));

8. Missing Error Handling

Problem: Tail Worker silently fails
Cause: No try/catch
Solution:

ctx.waitUntil((async () => {
  try {
    await fetch(env.ENDPOINT, { body: JSON.stringify(events) });
  } catch (error) {
    console.error("Tail error:", error);
    await env.FALLBACK_KV.put(`failed:${Date.now()}`, JSON.stringify(events));
  }
})());

9. Deployment Order

Problem: Producer deployment fails
Cause: Tail consumer not deployed yet
Solution: Deploy tail consumer FIRST

cd tail-worker && wrangler deploy
cd ../producer && wrangler deploy

10. No Event Retry

Problem: Events lost when handler fails
Cause: Failed invocations NOT retried
Solution: Implement fallback storage (see #8)

Debugging

View logs: wrangler tail my-tail-worker

Incremental testing:

  1. Verify receipt: console.log('Events:', events.length)
  2. Inspect structure: console.log(JSON.stringify(events[0], null, 2))
  3. Add external call with ctx.waitUntil()

Monitor dashboard: Check invocation count (matches producer?), error rate, CPU time

Testing

Add test endpoint to producer:

export default {
  async fetch(request) {
    if (request.url.includes('/test')) {
      console.log('Test log');
      throw new Error('Test error');
    }
    return new Response('OK');
  }
};

Trigger: curl https://producer.example.workers.dev/test

Common Errors

| Error | Cause | Solution | |-------|-------|----------| | "Tail consumer not found" | Not deployed | Deploy tail Worker first | | "No tail handler" | Missing tail() | Add to default export | | "waitUntil is not a function" | Missing ctx | Add ctx parameter | | Timeout | Blocking await | Use ctx.waitUntil() |

Performance Notes

  • Max 100 events per invocation
  • Each consumer receives all events independently
  • CPU limits same as regular Workers
  • For high volume, use Durable Objects batching