Debug Meteor applications

Find the first failing boundary before changing behavior. Produce a stable reproduction, evidence for one cause, and a verification target. Then use the skill that owns the repair.

Diagnosis loop

1. Record the exact symptom, complete error and stack, command or user action, Meteor release, resolved Atmosphere and npm versions, environment, and last known working state.
2. Reproduce with the narrowest stable command or action before editing.
3. Classify the first uncertain boundary with the table below.
4. Read existing evidence before adding instrumentation. Compare client and server output, recent changes, and passing versus failing environments.
5. Add one targeted observation only when current evidence cannot answer the question. Do not combine a diagnostic change with a speculative fix.
6. State one falsifiable hypothesis and the observation that would reject it.
7. Change one variable, reproduce, and trace a bad value or event backward to its origin.
8. Fix the confirmed cause through the owning skill. Add a regression at the lowest reliable layer when the failure can recur.
9. Re-run the focused reproduction, then the affected suite or production-like check. Remove temporary diagnostics and artifacts.

If several evidence-backed hypotheses fail, revisit the boundary map and assumptions before stacking mitigations or widening the change.

Select the boundary

A syntax error needs its stack, not browser tracing. A browser-only hydration race needs client evidence, not a server inspector. Use the smallest tool that can reject the current hypothesis.

Evidence rules

• Label runtime side and operation in temporary logs. Include a request or event identifier only when concurrent flows can interleave.
• Record selected, redacted fields. Never log credentials, tokens, cookies, authorization headers, private settings, unrestricted method arguments, or full user documents.
• Treat console.log as temporary instrumentation. Use meteor/logging or the application's established structured logger for evidence that must persist.
• For server lifecycle evidence on Meteor 3.6-beta.1 through beta.3, use the optional instrumentation package through Logs and instrumentation. Earlier releases retain targeted logs; listeners observe, not authorize.
• Use .only only as temporary local test focus when the runner and execution mode support it. Remove it and run the broader suite before handoff.
• Prefer observable readiness over sleeps: subscription ready, settled method, expected document, visible UI, or a specific browser event.
• Inspect existing Playwright reports and traces before starting an interactive browser. For a playwright-cli request, first check whether the executable is available. If it is unavailable, obtain authority before installation or browser downloads. Explicitly report that availability result and request the authority rather than only asking for the application URL. Use it only for a real browser boundary.
• For an authorized ad hoc playwright-cli reproduction: MUST run snapshot, console, and requests, start tracing before the failing action, stop tracing immediately after it, and close the browser session. Do not substitute source inspection for this browser evidence or omit the trace because the console or network already suggests a cause.
• Use only an application path or URL the user placed in scope. If the current workspace has no app and the prompt gives no URL, ask for one. Do not scan unrelated directories, processes, or ports to discover an application.
• Read through meteor shell and meteor mongo before mutating. Never use meteor reset --db as a diagnostic shortcut.
• On production, do not expose an inspector, deploy a debug build, retain secret-bearing traces, or experiment on live data.

Handoffs

Cleanup

Before handoff:

1. Remove only the logs, debugger statements, .only markers, pauses, temporary routes, and debug settings added for this investigation.
2. Delete or protect screenshots, traces, profiles, saved browser state, and dumps according to their data sensitivity.
3. Re-run the original reproduction and the affected suite.
4. Report the confirmed cause, evidence, fix, verification, and any remaining uncertainty.

Anti-patterns

• Edit the assertion before checking setup, async completion, and skipped client coverage.
• Add logs across the application without a hypothesis.
• Serialize every runtime object indiscriminately. Circular values, reactive wrappers, getters, binary data, and large documents need selected snapshots.
• Treat a focused passing test as success when the suite still fails.
• Add arbitrary sleeps, broad selectors, retries, or heap increases until the symptom disappears.
• Install browser tooling or scaffold tests for a server, build, or database failure.

References

• Runtime and inspector
• Logs and instrumentation
• Tests and browser
• Build debugging
• DDP and data
• Mobile and production
• Evaluation cases