error-handling

name: error-handling description: Debug and resolve common errors in TypeScript, Jest tests, ESLint, and dependency validation.

Error Handling

Use this skill when you encounter errors during development, testing, or build processes.

1. TypeScript Errors

Common Errors and Fixes

Debugging Workflow

1. Run npm run type-check to see all errors.
2. Focus on the first error (later errors are often cascading).
3. Check if the error is in your code or a library type definition.

Example: Fixing TS2307

Error:

error TS2307: Cannot find module 'shared/types/blog' or its corresponding type declarations.

Diagnosis: Path alias not resolving.

Fix: Verify tsconfig.json has the alias:

"paths": {
  "shared/*": ["src/shared/*"]
}

2. Jest Test Failures

Project Test Configuration

This project uses a unified Jest entrypoint that runs both environments:

# Run ALL tests (recommended)
npm test

# Run only UI tests
npm run test:ui

# Run only Server tests
npm run test:server

The unified config (jest.config.ts) delegates to:

• jest.browser.ts → UI tests (src/ui/**/*.test.tsx) in jsdom environment
• jest.node.ts → Server tests (src/server/**/*.test.ts, src/shared/**/*.test.ts) in Node environment

Common Patterns (Both Environments)

UI-Specific Issues (jest.browser.ts)

Server-Specific Issues (jest.node.ts)

Debugging Workflow

1. Run the single failing test with verbose output:

   For UI tests:

   npx jest src/ui/path/to/test.test.tsx --config jest.browser.ts --verbose
   

   For Server tests:

   npx jest src/server/path/to/test.test.ts --config jest.node.ts --verbose
   

2. Check if the mock is set up correctly.

3. Verify beforeEach/afterEach cleanup.

Example: Fixing ESM Mock Issues (UI)

Error:

SyntaxError: Cannot use import statement outside a module

Diagnosis: ESM library not transpiled by Jest.

Fix: Add to jest config's transformIgnorePatterns or mock the module:

jest.mock('react-markdown', () => ({
  __esModule: true,
  default: ({ children }: { children: string }) => <div>{children}</div>,
}));

Example: Fixing "act()" Warnings (UI)

Error:

Warning: An update to Component inside a test was not wrapped in act(...)

Fix: Wrap assertions in waitFor:

await waitFor(() => {
  expect(screen.getByText('Loaded')).toBeInTheDocument();
});

Example: Fixing NestJS Dependency Resolution (Server)

Error:

Nest can't resolve dependencies of the BlogService (?). Please make sure that the argument "BlogPostRepository" at index [0] is available in the RootTestModule context.

Fix: Provide the repository in your test module:

const moduleRef = await Test.createTestingModule({
  imports: [
    TypeOrmModule.forRoot({
      type: 'better-sqlite3',
      database: ':memory:',
      entities: [BlogPost],
      synchronize: true,
    }),
    TypeOrmModule.forFeature([BlogPost]), // ← Register the repository
  ],
  providers: [BlogService],
}).compile();

Example: Fixing Database State Leaking (Server)

Problem: Tests pass individually but fail when run together.

Fix: Ensure each test uses a fresh in-memory database:

beforeAll(async () => {
  const moduleRef = await Test.createTestingModule({
    imports: [
      TypeOrmModule.forRoot({
        type: 'better-sqlite3',
        database: ':memory:', // ← Fresh DB per test suite
        synchronize: true,
        entities: [BlogPost],
      }),
      BlogModule,
    ],
  }).compile();

  app = moduleRef.createNestApplication();
  await app.init();
});

afterAll(async () => {
  await app.close(); // ← Always close to release resources
});

3. ESLint / Prettier Errors

Quick Fixes

# Auto-fix all fixable issues
npm run format

# Check without fixing
npm run lint

Common ESLint Errors

Example: Fixing react-hooks/exhaustive-deps (UI)

Error:

React Hook useEffect has a missing dependency: 'fetchData'

Fix Options:

1. Add the dependency (preferred):

   useEffect(() => {
     fetchData();
   }, [fetchData]);
   

2. Use useCallback to stabilize the function:

   const fetchData = useCallback(() => {
     /* ... */
   }, []);
   useEffect(() => {
     fetchData();
   }, [fetchData]);
   

4. Dependency Cruiser Violations

Understanding Violations

Run the check:

npm run depcruise:verify

Common Violations and Fixes

Example: Fixing Cross-Boundary Import

Error:

error no-orphans: src/ui/containers/blog/hooks/useBlog.ts → src/server/modules/blog/blog.entity.ts

Fix: The UI should not import server entities. Create a shared type:

1. Create src/shared/types/blog.ts:

   export interface BlogPost {
     id: string;
     title: string;
     // ... shared fields
   }
   

2. Update UI to import from shared:

   import { BlogPost } from 'shared/types/blog';
   

5. Build Errors

NestJS Build Failures

npm run build:server

Webpack Build Failures

npm run build:ui

6. Runtime Errors

Server Errors (NestJS)

Client Errors (React)

7. Escalation

If the error persists after following this guide:

1. Search the error message in project issues.
2. Check if the error is in a third-party library (update or file issue).
3. Ask for help with the full error message and reproduction steps.