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

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.

When the Insomnia desktop app fails to start or builds break in the Kong/insomnia repository, the root 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 mandates Node.js ≥24 and npm ≥11. Mismatched versions cause cryptic native module errors or install failures.

Check your current versions:

node -v  # should be >= 24

npm -v   # should be >= 11

If versions differ, switch using the .nvmrc file as documented in AGENTS.md:

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) runs git clean -dfX to purge untracked files and caches.

npm run clean

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

Execute Diagnostic Scripts

The root 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:

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:

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:

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:

# 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 pin runtime libraries like ajv (JSON schema validation) and @getinsomnia/node-libcurl. If runtime exceptions reference these libraries, reinstall the specific versions:

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.

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 → models.ts → 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}