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:

   bash

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

   For Server tests:

   bash

   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):

   typescript

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

2. •

   Use useCallback to stabilize the function:

   typescript

   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:

   typescript

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

2. •

   Update UI to import from shared:

   typescript

   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.