# Troubleshooting Steps for Insomnia: A package.json-Based Workflow

> Resolve Insomnia build or runtime issues by checking Node npm versions and running package.json scripts like npm run clean lint type-check and check-cycle-references. Essential troubleshooting steps.

- Repository: [Kong/insomnia](https://github.com/Kong/insomnia)
- Tags: how-to-guide
- Published: 2026-06-27

---

**Most Insomnia build and runtime issues can be resolved by verifying Node.js ≥24 and npm ≥11, running `npm run clean` to wipe artifacts, and executing the built-in diagnostic scripts (`lint`, `type-check`, `check-cycle-references`) defined in the root [`package.json`](https://github.com/Kong/insomnia/blob/main/package.json).**

When the Insomnia desktop app fails to start or builds break in the Kong/insomnia repository, the root [`package.json`](https://github.com/Kong/insomnia/blob/main/package.json) contains the diagnostic roadmap. This monorepo uses TypeScript, Vite, and Electron, with all tooling centralized in the top-level manifest. These troubleshooting steps for Insomnia leverage the scripts and engine requirements defined in that file to systematically isolate and resolve failures.

## Verify Node.js and npm Compatibility

The `engines` field in [`package.json`](https://github.com/Kong/insomnia/blob/main/package.json) mandates **Node.js ≥24** and **npm ≥11**. Mismatched versions cause cryptic native module errors or install failures.

Check your current versions:

```bash
node -v  # should be >= 24

npm -v   # should be >= 11

```

If versions differ, switch using the `.nvmrc` file as documented in [`AGENTS.md`](https://github.com/Kong/insomnia/blob/main/AGENTS.md):

```bash
fnm use "$(cat .nvmrc)"

```

Then install dependencies with `npm ci` to ensure exact locked versions across all workspaces.

## Clean the Working Tree

Stale build artifacts cause mysterious compilation errors. The `clean` script (line 33 in [`package.json`](https://github.com/Kong/insomnia/blob/main/package.json)) runs `git clean -dfX` to purge untracked files and caches.

```bash
npm run clean

```

Execute this before any deep troubleshooting to ensure a pristine state.

## Execute Diagnostic Scripts

The root [`package.json`](https://github.com/Kong/insomnia/blob/main/package.json) defines several health-check scripts that surface specific failure modes.

### Linting and Type Checking

- **`npm run lint`** (line 30): Runs ESLint across all workspaces to catch syntax errors and broken imports.
- **`npm run type-check`** (line 31): Executes `tsc --noEmit` in every package to identify TypeScript compilation errors without emitting files.

### Native Module Verification

- **`npm run install-libcurl-electron`** (line 34): Recompiles `@getinsomnia/node-libcurl` for the Electron runtime (v41.0.3). Use this when encountering `ERR_DLOPEN_FAILED` errors.
- **`npm run install-libcurl-node`** (line 35): Recompiles the bindings for Node.js (v24.14.0).

### Circular Dependency Detection

- **`npm run check-cycle-references`** (line 47): Uses `madge` to detect circular imports across `packages/*` that can cause runtime crashes or dead code elimination issues.

### Unit Testing

- **`npm test`** (line 32): Runs all Jest/Vitest suites to expose regressions.

**Typical diagnostic workflow:**

```bash
npm run clean
npm ci
npm run lint
npm run type-check
npm run check-cycle-references
npm test

```

## Fix Development and Packaging Errors

### Development Server Issues

If `npm run dev` (line 28) fails to launch the UI, verify Electron entry points compiled correctly:

```bash
npm run build:electron-entrypoints -w insomnia

```

For hot-reload failures, use **`npm run dev:autoRestart`** (line 29), which watches source files and triggers rebuilds automatically.

### Packaging Failures

When `npm run app-package` (line 40) fails, it often indicates missing native dependencies. Re-run the libcurl installer before packaging:

```bash
npm run install-libcurl-electron
npm run app-package

```

## Validate Plugin Integrity

The `postinstall` script (line 46) runs `patch-package`, verifies bundled plugins via `verify-bundle-plugins`, and installs Electron-specific libcurl bindings. If a third-party plugin crashes the app:

1. Remove the offending plugin from `packages/insomnia/plugin/...`
2. Re-run `npm run postinstall`

This script outputs detailed verification reports referencing specific plugin files when checks fail.

## Isolate Workspace-Specific Problems

The `workspaces` array (lines 17-26) defines the monorepo structure. Narrow failures by targeting specific packages:

```bash

# Lint only the UI workspace

npm run lint -w insomnia

# Test only the testing utilities

npm test -w insomnia-testing

# Type-check only data models

npm run type-check -w insomnia-data

```

This isolation prevents unrelated workspace noise from obscuring the root cause.

## Audit Critical Dependencies

Lines 85-88 in [`package.json`](https://github.com/Kong/insomnia/blob/main/package.json) pin runtime libraries like `ajv` (JSON schema validation) and `@getinsomnia/node-libcurl`. If runtime exceptions reference these libraries, reinstall the specific versions:

```bash
npm install @getinsomnia/node-libcurl@3.2.2 ajv@^8.17.1

```

## Summary

- **Verify environment**: Ensure Node.js ≥24 and npm ≥11 using `fnm` and `.nvmrc` before running `npm ci`.
- **Clean slate**: Execute `npm run clean` to remove stale artifacts via `git clean -dfX` (line 33).
- **Run diagnostics**: Use `npm run lint` (line 30), `npm run type-check` (line 31), and `npm run check-cycle-references` (line 47) to catch code-level issues.
- **Fix native modules**: Rebuild libcurl bindings with `npm run install-libcurl-electron` when encountering load failures.
- **Isolate workspaces**: Use the `-w` flag to target specific packages like `insomnia` or `insomnia-testing`.
- **Validate plugins**: Re-run `npm run postinstall` (line 46) after removing problematic plugins.

## Frequently Asked Questions

### Why does Insomnia fail to start with "Failed to load native module" errors?

This indicates a mismatch between the compiled `@getinsomnia/node-libcurl` bindings and your current Node.js or Electron version. Run `npm run install-libcurl-electron` to recompile the native module for the correct runtime. Ensure you are using Node.js ≥24 as specified in the `engines` field of [`package.json`](https://github.com/Kong/insomnia/blob/main/package.json).

### How do I fix circular dependency warnings in the Insomnia codebase?

Execute `npm run check-cycle-references`, which runs `madge` on the `packages/*` directory. The output lists circular import chains (e.g., [`request.ts`](https://github.com/Kong/insomnia/blob/main/request.ts) → [`models.ts`](https://github.com/Kong/insomnia/blob/main/models.ts) → [`request.ts`](https://github.com/Kong/insomnia/blob/main/request.ts)). Refactor by extracting shared utilities into a separate module to break the cycle.

### What should I do if the development server won't hot-reload my changes?

Use `npm run dev:autoRestart` instead of `npm run dev`. This script (line 29) watches source files and automatically triggers rebuilds when it detects changes. If the UI still fails to appear, verify the Electron entry points compiled successfully with `npm run build:electron-entrypoints -w insomnia`.

### How do I troubleshoot a failing build in only one part of the monorepo?

Use npm workspaces isolation with the `-w` flag. For example, run `npm run lint -w insomnia` to lint only the main application workspace, or `npm test -w insomnia-testing` to run tests only for the testing utilities. This narrows the scope and eliminates noise from other packages.