How to debug complex async JavaScript in Replit

Create a new Node.js Repl and add a file called async-debug.js. Populate it with a set of async functions that simulate real-world operations like API calls and database queries. These functions will intentionally include common bugs such as missing await keywords, unhandled rejections, and race conditions. Having a controlled test file lets you practice debugging techniques without risking your main project code. Set async-debug.js as the entrypoint in your .replit file so clicking Run executes it directly.

1// async-debug.js
2const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
3
4async function fetchUser(id) {
5  await delay(Math.random() * 1000);
6  if (id === 3) throw new Error(`User ${id} not found`);
7  return { id, name: `User_${id}`, loaded: Date.now() };
8}
9
10async function fetchAllUsers() {
11  const ids = [1, 2, 3, 4, 5];
12  const users = await Promise.all(ids.map(id => fetchUser(id)));
13  return users;
14}
15
16fetchAllUsers()
17  .then(users => console.log('All users:', users))
18  .catch(err => console.error('Failed:', err.message));

The most effective async debugging technique is adding timestamped log entries that show exactly when each operation starts, completes, or fails. Create a simple logger function that prefixes every message with a high-resolution timestamp and a label. Wrap each async call with log statements before and after. This reveals the actual execution order, which often differs from what you expect. In the Replit Console, you can scroll through these entries to see overlapping operations and identify where timing issues occur.

1// Add at the top of async-debug.js
2const start = Date.now();
3function log(label, msg) {
4  const elapsed = Date.now() - start;
5  console.log(`[${elapsed}ms] [${label}] ${msg}`);
6}
7
8async function fetchUser(id) {
9  log('fetchUser', `START id=${id}`);
10  await delay(Math.random() * 1000);
11  if (id === 3) {
12    log('fetchUser', `ERROR id=${id}`);
13    throw new Error(`User ${id} not found`);
14  }
15  log('fetchUser', `DONE id=${id}`);
16  return { id, name: `User_${id}`, loaded: Date.now() };
17}

The original code uses Promise.all, which rejects immediately when any single Promise fails. This means you lose all successful results. Replace Promise.all with Promise.allSettled, which waits for every Promise to complete regardless of outcome. Each result is an object with a status of either 'fulfilled' (with a value property) or 'rejected' (with a reason property). This pattern is essential for any operation where partial success is acceptable, such as loading a dashboard where some widgets might fail without breaking the entire page.

1async function fetchAllUsers() {
2  const ids = [1, 2, 3, 4, 5];
3  const results = await Promise.allSettled(ids.map(id => fetchUser(id)));
4
5  const users = [];
6  const errors = [];
7
8  results.forEach((result, index) => {
9    if (result.status === 'fulfilled') {
10      users.push(result.value);
11    } else {
12      errors.push({ id: ids[index], error: result.reason.message });
13      log('fetchAllUsers', `User ${ids[index]} failed: ${result.reason.message}`);
14    }
15  });
16
17  log('fetchAllUsers', `Loaded ${users.length} users, ${errors.length} failed`);
18  return { users, errors };
19}

Race conditions happen when multiple async operations read or write shared state simultaneously and the final result depends on which finishes first. To isolate a race condition, temporarily replace concurrent execution with sequential execution using a for...of loop with await. If the bug disappears when operations run one at a time, you have confirmed a race condition. Then add proper synchronization such as a mutex pattern or restructure the code to avoid shared mutable state. This technique is the fastest way to diagnose intermittent bugs that only appear sometimes.

1// Sequential version for debugging race conditions
2async function fetchAllUsersSequential() {
3  const ids = [1, 2, 3, 4, 5];
4  const users = [];
5
6  for (const id of ids) {
7    try {
8      const user = await fetchUser(id);
9      users.push(user);
10      log('sequential', `Got user ${id}`);
11    } catch (err) {
12      log('sequential', `Skipped user ${id}: ${err.message}`);
13    }
14  }
15
16  return users;
17}
18
19// Compare outputs
20fetchAllUsersSequential().then(users => {
21  console.log('Sequential result:', users.length, 'users');
22});

Unhandled Promise rejections are silent killers in Node.js applications. They crash the process in newer Node versions or silently swallow errors in older ones. Add a global handler at the top of your entry file that catches any unhandled rejection and logs it with full context. In Replit, these errors appear in the Console output. This is especially important because Replit's Console only shows stdout and stderr from your process, so without an explicit handler, some async errors may disappear entirely.

1// Add at the very top of your entry file
2process.on('unhandledRejection', (reason, promise) => {
3  console.error('=== UNHANDLED REJECTION ===');
4  console.error('Reason:', reason);
5  console.error('Stack:', reason?.stack || 'No stack trace');
6  console.error('===========================');
7});
8
9process.on('uncaughtException', (err) => {
10  console.error('=== UNCAUGHT EXCEPTION ===');
11  console.error(err);
12  console.error('==========================');
13  process.exit(1);
14});

For complex async bugs that resist logging-based debugging, use Node.js built-in inspector. Open the Shell tab in Replit and run your script with the --inspect-brk flag. This pauses execution at the first line and starts a debugging protocol. While Replit does not have a built-in visual debugger, you can use the debugger statement in your code combined with console inspection. Alternatively, add strategic debugger breakpoints and use the Node.js REPL to inspect variables at specific points in the async flow.

1# In Replit Shell, run with inspect flag
2node --inspect-brk async-debug.js
3
4# Or use the built-in Node.js debugger
5node inspect async-debug.js
6
7# Inside the debugger:
8# Type 'c' to continue to next breakpoint
9# Type 'repl' to inspect variables
10# Type 'n' to step to next line
11# Type '.exit' to quit