1# Gotchas & Troubleshooting
2 
3## Miniflare Limitations
4 
5**Not supported:**
6- Analytics Engine (use mocks)
7- Cloudflare Images/Stream
8- Browser Rendering API
9- Tail Workers
10- Workers for Platforms (partial support)
11 
12**Behavior differences from production:**
13- Runs workerd locally, not Cloudflare edge
14- Storage is local (filesystem/memory), not distributed
15- `Request.cf` is cached/mocked, not real edge data
16- Performance differs from edge
17- Caching implementation may vary slightly
18 
19## Common Errors
20 
21### "Cannot find module"
22**Cause:** Module path wrong or `modulesRules` not configured  
23**Solution:**
24```js
25new Miniflare({
26  modules: true,
27  modulesRules: [{ type: "ESModule", include: ["**/*.js"] }],
28});
29```
30 
31### "Data not persisting"
32**Cause:** Persist paths are files, not directories  
33**Solution:**
34```js
35kvPersist: "./data/kv",  // Directory, not file
36```
37 
38### "Cannot run TypeScript"
39**Cause:** Miniflare doesn't transpile TypeScript  
40**Solution:** Build first with esbuild/tsc, then run compiled JS
41 
42### "`request.cf` is undefined"
43**Cause:** CF data not configured  
44**Solution:**
45```js
46new Miniflare({ cf: true }); // Or cf: "./cf.json"
47```
48 
49### "EADDRINUSE" port conflict
50**Cause:** Multiple instances using same port  
51**Solution:** Use `dispatchFetch()` (no HTTP server) or `port: 0` for auto-assign
52 
53### "Durable Object not found"
54**Cause:** Class export doesn't match config name  
55**Solution:**
56```js
57export class Counter {} // Must match
58new Miniflare({ durableObjects: { COUNTER: "Counter" } });
59```
60 
61## Debugging
62 
63**Enable verbose logging:**
64```js
65import { Log, LogLevel } from "miniflare";
66new Miniflare({ log: new Log(LogLevel.DEBUG) });
67```
68 
69**Chrome DevTools:**
70```js
71const url = await mf.getInspectorURL();
72console.log(`DevTools: ${url}`); // Open in Chrome
73```
74 
75**Inspect bindings:**
76```js
77const env = await mf.getBindings();
78console.log(Object.keys(env));
79```
80 
81**Verify storage:**
82```js
83const ns = await mf.getKVNamespace("TEST");
84const { keys } = await ns.list();
85```
86 
87## Best Practices
88 
89**✓ Do:**
90- Use `dispatchFetch()` for tests (no HTTP server)
91- In-memory storage for CI (omit persist options)
92- New instances per test for isolation
93- Type-safe bindings with interfaces
94- `await mf.dispose()` in cleanup
95 
96**✗ Avoid:**
97- HTTP server in tests
98- Shared instances without cleanup
99- Old compatibility dates (use 2026+)
100 
101## Migration Guides
102 
103### From Miniflare 2.x to 3+
104 
105Breaking changes in v3+:
106 
107| v2 | v3+ |
108|----|-----|
109| `getBindings()` sync | `getBindings()` returns Promise |
110| `ready` is void | `ready` returns `Promise<URL>` |
111| service-worker-mock | Built on workerd |
112| Different options | Restructured constructor |
113 
114**Example migration:**
115```js
116// v2
117const bindings = mf.getBindings();
118mf.ready; // void
119 
120// v3+
121const bindings = await mf.getBindings();
122const url = await mf.ready; // Promise<URL>
123```
124 
125### From unstable_dev to Miniflare
126 
127```js
128// Old (deprecated)
129import { unstable_dev } from "wrangler";
130const worker = await unstable_dev("src/index.ts");
131 
132// New
133import { Miniflare } from "miniflare";
134const mf = new Miniflare({ scriptPath: "src/index.ts" });
135```
136 
137### From Wrangler Dev
138 
139Miniflare doesn't auto-read `wrangler.toml`:
140 
141```js
142// Translate manually:
143new Miniflare({
144  scriptPath: "dist/worker.js",
145  compatibilityDate: "2026-01-01",
146  kvNamespaces: ["KV"],
147  bindings: { API_KEY: process.env.API_KEY },
148});
149```
150 
151## Resource Limits
152 
153| Limit | Value | Notes |
154|-------|-------|-------|
155| CPU time | 30s default | Configurable via `scriptTimeout` |
156| Storage | Filesystem | Performance varies by disk |
157| Memory | System dependent | No artificial limits |
158| Request.cf | Cached/mocked | Not live edge data |
159 
160See [patterns.md](./patterns.md) for testing examples.
161