switch-dimension/check-logs

Log Doctor

Find errors in dev server and task logs, diagnose them, and fix the source code.

When to use

This skill covers two scenarios:

1. Terminal / Bash output — The user ran a dev server or build command and sees errors
2. Background tasks — The user has running subagent tasks and wants to check them for errors

Workflow

1. Gather logs

Collect error output from all available sources in parallel:

From Bash / terminal:

• Check if there's a running dev server log file (e.g., /tmp/smoke-test-server.log or similar)
• If the user just ran a command, the error is likely in the recent Bash output already visible in conversation context — no need to re-run anything
• If a dev server is running in the background, read its log file

From background tasks:

• Use TaskList to see all active tasks
• Use TaskGet on any tasks with status in_progress or failed to read their output
• Look for error patterns in the task output

From the dev server directly:

• Before starting a dev server, check if one is already running on the expected port:

  lsof -i :<port> -sTCP:LISTEN
  

• If the port is in use, the server is likely already running — read its output from the existing log file or ask the user where to find the logs instead of starting a new instance
• If the port is free and no logs are available, start the dev server to reproduce:

  npm run dev 2>&1 | head -100
  

• If you're unsure which port the project uses, check package.json scripts and framework config first. If still unclear, ask the user rather than guessing
• For build errors: npm run build 2>&1 | head -200

2. Identify the errors

Scan the collected logs for these patterns:

Next.js specific:

• Error: or error - prefixed lines
• Module not found — missing import or package
• Type error — TypeScript issues
• Unhandled Runtime Error — runtime crashes
• Failed to compile — build-blocking errors
• Warning: lines that indicate real problems (hydration mismatch, missing key, etc.)
• ENOENT or EACCES — file system issues
• Server component / client component boundary violations
• next.config parsing errors

Vite specific:

• [vite] prefixed error lines
• Failed to resolve import — missing module
• Pre-transform error — plugin failures
• TypeError or ReferenceError in SSR
• HMR errors ([hmr])
• optimized dependencies changed loops
• Config file errors

General:

• Stack traces (lines with at ...)
• EADDRINUSE — port conflict
• SyntaxError — malformed code
• Cannot find module — missing dependency
• Segfaults or out-of-memory errors
• npm/yarn/pnpm install failures

3. Diagnose root cause

For each error found:

1. Read the referenced file and line — the stack trace or error message almost always points to a specific file and line number. Read it.
2. Understand the context — read surrounding code, imports, and related files to understand why the error occurs
3. Check package.json — if it's a missing module, check if the package is listed in dependencies
4. Check config files — for config-related errors, read next.config.js, vite.config.ts, tsconfig.json, etc.

4. Fix the errors

Apply fixes directly — don't just suggest them. Common fixes:

| Error | Fix | |-------|-----| | Module not found | Install the package or fix the import path | | Type error | Fix the type issue in the source file | | Failed to compile (syntax) | Fix the syntax error | | EADDRINUSE | Find and kill the process on that port | | Hydration mismatch | Fix the server/client rendering discrepancy | | Missing env variable | Tell the user which .env variable is needed | | Cannot find module (local) | Fix the relative import path |

For each fix:

1. Edit the file using the Edit tool
2. If a package needs installing, run npm install <package> (or the appropriate package manager)
3. If it's a config issue, edit the config file

After fixing, verify by running the build or dev server again and checking that the error is gone.

5. Report findings

Give the user a clear summary:

## Log Doctor Report

**Source:** <where you found the logs>

### Errors Found: N

**1. <Error title>**
- File: `path/to/file.ts:42`
- Error: <the error message>
- Cause: <why it happened>
- Fix: <what you did>
- Status: Fixed / Needs user action

### Verification
<did the fix work? paste the clean output or remaining errors>

If an error requires user input (like adding an env variable or choosing between options), explain what's needed and ask.

Important notes

• Always read the actual source file before attempting a fix — don't guess based on the error message alone
• If multiple errors exist, fix them in dependency order (e.g., fix missing imports before type errors)
• If an error is in node_modules, the fix is usually in the project's code or config, not in the module itself — don't edit node_modules
• If you can't determine the fix, explain the error clearly and suggest what the user should investigate
• Don't restart the dev server unless you need to verify a fix — the user may have it running intentionally
• For background tasks, use TaskGet to read output — don't stop or restart tasks without asking