Debugging and Error Fixing with Cursor

Debugging is one of the most time-consuming parts of software development, and one of the areas where Cursor provides the most immediate value. By making it easy to share error context with AI, Cursor turns debugging from a lonely slog into a shared investigation. This lesson covers the main debugging workflows available in Cursor.

What You'll Learn

• How to share errors and terminal output with the agent in the side panel
• How to let Agent mode run commands and fix errors itself, and when to reach for Debug mode
• How to use Cmd+K for targeted error fixes
• A systematic debugging strategy using the agent as a thinking partner
• How to read stack traces with AI help
• The limits of AI debugging and when to rely on your own judgment

Pasting Error Messages into the Chat

The simplest debugging technique is copying an error message and pasting it into the Agent side panel (Cmd+I or Cmd+L).

Why This Works

Error messages contain structured information (error type, message text, file path, line number) that AI is very good at interpreting. Rather than searching forums or reading documentation from scratch, you can ask Cursor to explain the error in context and suggest fixes.

Example

Suppose you see this error in your browser console:

TypeError: Cannot read properties of undefined (reading 'map')
    at ProductList (ProductList.tsx:24:18)
    at renderWithHooks (react-dom.development.js:14985:18)

Paste it into the chat and add context:

I'm getting this error in my React app. The ProductList component receives products as a prop. @ProductList.tsx

Cursor will identify that products is undefined when the component first renders (a very common pattern), explain why that makes .map() throw, and suggest an optional chaining guard (products?.map(...)) or a default value in the prop destructuring.

Tips for Better Results

• Always paste the full error, not just the message line
• Include or @-mention the relevant code alongside the error
• Mention what you were doing when the error occurred
• Describe what you expected to happen versus what happened

---

Using @Terminals to Share Terminal Output

When errors appear in your terminal rather than the browser, the @Terminals mention lets you bring that output into the chat without copying it by hand.

How It Works

Type @Terminals in the chat input and pick the terminal you want. Cursor pulls in its recent output as context. Then ask:

@Terminals Why is my server failing to start? What do these errors mean and how do I fix them?

This is especially useful for:

• Build failures (npm run build errors, TypeScript compilation errors)
• Server startup failures
• Test failures from npm test
• Database connection errors

You can also select some terminal output and press Cmd+Shift+L (Ctrl+Shift+L on Windows and Linux) to add just that selection to the chat.

Practical Example

You run npm run build and get a wall of TypeScript errors. Instead of reading through each one, mention the terminal and ask:

@Terminals I have TypeScript compilation errors after a refactor. List the distinct error types, explain what's causing each one, and suggest which order to fix them in.

Cursor will group the errors (missing types, incorrect generics, and so on), explain root causes, and often spot that many errors come from a single root cause. Fixing that one first may clear dozens of others.

---

Letting Agent Mode Fix Errors

In Agent mode, you often don't need to copy anything. The agent can run commands in the terminal itself, read the output, and react to it.

Let the Agent Run and Fix

Give it a goal that includes verification:

Run npm test. For each failing test, find the cause and fix it. Run the tests again until they pass, and tell me what you changed.

The agent will run the command, read the failures, open the relevant files, make changes, and re-run the tests. Depending on your settings, it may ask for your approval before running commands, or run trusted ones automatically.

Quick Actions on Errors

Cursor also offers quick ways to send an error straight to the agent, such as an option on terminal output or on a red squiggle in the editor. The exact labels can change between versions, but the idea is the same: one click puts the error into the chat as context.

When to Use This

Letting the agent fix errors on its own is best for:

• Straightforward, self-contained errors (a missing import, a typo in a variable name, a wrong type)
• Errors with a clear single cause
• Fast iteration during active development

For complex, multi-cause errors, especially ones that depend on system state or business logic, slow down. Work through the problem with the agent step by step, as described below.

Debug Mode for Tricky Bugs

Cursor also has a Debug mode, which you can pick from the mode menu (Shift+Tab, or Cmd+. / Ctrl+. in the chat input). It is built for hunting bugs using runtime evidence rather than guesses, so it is worth trying when a bug only shows up while the code runs. Features like this change often, so check Cursor's docs for how it currently works.

---

Selecting Broken Code and Using Cmd+K to Fix It

When you can see the problem code in the editor, selecting it and pressing Cmd+K is often the most direct fix.

The Workflow

1. Find the function or block causing the issue
2. Select it in the editor
3. Press Cmd+K
4. Describe the problem: "This function crashes when user is null. Add proper null handling."
5. Review the diff and accept

Example

You have a function that calculates a user's discount but throws when the user has no purchase history:

function calculateDiscount(user: User): number {
  const totalSpent = user.purchases.reduce((sum, p) => sum + p.amount, 0);
  return totalSpent > 500 ? 0.1 : 0;
}

Select this function, press Cmd+K, and type: "This crashes if user.purchases is undefined or empty. Fix it with safe defaults."

Cursor will add a null check and a fallback, producing something like:

function calculateDiscount(user: User): number {
  const purchases = user.purchases ?? [];
  const totalSpent = purchases.reduce((sum, p) => sum + p.amount, 0);
  return totalSpent > 500 ? 0.1 : 0;
}

Review the change. It's often exactly right, but sometimes you'll want to adjust the fallback behavior or error handling.

---

A Systematic Debugging Strategy

For harder bugs where the cause isn't obvious, treat the agent as a structured thinking partner. Ask mode is a good fit for the early steps, since it can read your code without changing anything. Follow this sequence:

Step 1: Explain the Error

Start by asking Cursor what the error means, not just in general but in your specific context.

This is an ECONNREFUSED error when my app tries to connect to Redis. Explain what this means and the common causes in a Node.js/Docker environment.

Step 2: Ask for Hypotheses

Once you understand the error, ask for a ranked list of likely causes:

Given that this error only happens in production (not locally), what are the most likely causes? List them from most to least probable.

Step 3: Design Diagnostic Steps

Ask how to test each hypothesis:

How can I verify whether the Redis connection string is correctly set in my production environment? What should I check?

Step 4: Apply the Fix

Once you've found the cause, switch to Agent mode or use Cmd+K to implement the fix. For infrastructure issues like this one, the agent can also help you write the correct configuration or environment variable setup.

Step 5: Verify

After applying a fix, ask for help verifying it:

I've updated the Redis connection string. What test can I run to confirm the connection works before deploying?

---

Understanding Stack Traces with AI

Stack traces are dense and hard to read, especially in frameworks that add many internal layers between your code and the error.

How to Share a Stack Trace

Paste the full stack trace into the chat. Don't trim it. The middle and lower frames often contain important context even if they look like library internals.

Here's a stack trace from a crash in my Express app. Identify which line is in my code (not library code), explain what sequence of calls led to the crash, and suggest where the actual bug likely is.

Cursor will parse the trace, highlight the frames from your application code (versus Node.js internals or npm packages), and walk you through the call sequence that led to the error.

React Error Boundaries and Component Trees

For React crashes, the component stack can be confusing. Ask Cursor to explain it:

Here's a React error boundary log including the component stack. Which component caused the error, and what was the render path that led to it?

---

Rubber-Duck Debugging with AI

Sometimes bugs are solved not by finding a fix but by describing the problem clearly enough that the answer becomes obvious. This is rubber-duck debugging: explaining your problem to an object (traditionally a rubber duck) helps you think it through.

Cursor makes an excellent rubber duck because it actually responds.

How to Do It

Describe your problem in detail, as if explaining it to someone who has never seen your codebase:

I have a race condition in my data-loading logic. When a user navigates quickly between pages, the data from the first page sometimes appears on the second page. I'm using React Query with queryClient.setQueryData. @pages/ProductPage.tsx Walk through what might be happening and where the race condition could come from.

Writing this explanation often surfaces the issue on its own. When it doesn't, Cursor's reply adds a fresh perspective and often finds the exact problem.

---

Adding Logging and Debugging Code with Cmd+K

When a bug is elusive and you need to add instrumentation before you can understand it, Cmd+K can generate logging statements quickly.

Add Strategic Logging

Select a function and ask:

Add console.log statements to trace the inputs, intermediate values, and output of this function. Use clear labels so I can read the logs easily.

Add Conditional Breakpoint Logic

Add a debugger statement that only triggers when userId is null, so I can inspect the call stack at that point.

Clean Up After Debugging

Once you've found and fixed the bug, select the debug code you added and use Cmd+K to remove it:

Remove all the debug logging I added to this function and restore it to a production-ready state.

---

Limitations: When AI Misdiagnoses

AI debugging help is powerful but not perfect. Knowing how it fails helps you avoid being misled.

Common Misdiagnoses

• Plausible but wrong root cause: AI may fix a symptom without addressing the underlying cause
• Missing runtime context: Unless it can run your code or see logs, AI can't see your actual data, environment variables, or database state, so bugs that depend on runtime conditions may be misdiagnosed
• Framework-specific subtleties: Bugs tied to a specific library version may be explained incorrectly if the model doesn't know that exact version
• Race conditions and async bugs: These are hard to reason about from code alone, so AI may miss them or propose fixes that don't fully solve the timing issue

How to Protect Yourself

• Test every suggested fix before accepting it
• Ask Cursor to explain why a fix works, not just what it is. If the explanation doesn't make sense, the fix may be wrong
• If a fix doesn't work, say so clearly: "That fix didn't work. The error still occurs when X. Let's try a different approach."
• If the agent has gone down the wrong path, use a checkpoint in the chat timeline to restore your files to an earlier point
• For subtle bugs, treat AI suggestions as hypotheses to test, not conclusions to accept

---

Key Takeaways

• Paste full errors with context: Give Cursor the error message, the relevant code, and what you expected. This greatly improves the quality of the answer
• @Terminals saves time: Use it to pull in terminal output without manual copying, especially for build and test failures
• Let Agent mode run and fix simple errors: It can run commands, read the output, and iterate, but slow down for complex bugs
• Debug mode exists for tricky bugs: Try it when a bug only appears at runtime and guessing isn't working
• Use a systematic strategy: Work through explain, hypothesize, diagnose, fix, and verify rather than jumping straight to a fix
• Stack traces are readable with AI help: Paste the full trace and ask Cursor to find your code's frames and explain the call sequence
• Rubber-duck debugging works with AI: Describing a problem in detail often surfaces the solution before the AI even replies
• AI can misdiagnose: Always verify fixes, ask for explanations, and treat suggestions as hypotheses, especially for runtime-dependent or async bugs