14 - Troubleshooting

1) Black Screen on Launch

Symptoms

• Electron opens a blank/black window.

Likely Causes

1. Running production entry without renderer output
2. Renderer failed to load

What to Do

1. For development: run npm run dev
2. For production-style run: use npm run start (builds first)
3. Build explicitly to verify: npm run build

Main process includes startup error page fallback to show load details.

2) App Says Library Root Is Required

Symptoms

• Save/import actions fail with root path error.

Fix

• Choose library root from sidebar action.
• Confirm root path displays in sidebar.

3) Request Fails Before Send

Symptoms

• Immediate URL validation error.

Fix

• Ensure URL is non-empty and valid.
• Check unresolved placeholders like {{baseUrl}} if folder variables are missing.

4) Import Fails with No Operations

Symptoms

• Import dialog returns no operations or unsupported document errors.

Fix

• Verify source is OpenAPI/Swagger/Postman format.
• Ensure paths exist for OpenAPI/Swagger.
• For Postman, verify items contain request URL values.

5) Import Reports Conflicts

Symptoms

• Preview entries marked conflict or match.

Meaning

• match: same source identity + operation/item key already imported
• conflict: desired file path already used by different request

Fix

• Pick appropriate import mode:
  • create-new
  • replace-existing
  • skip-existing

6) URL Variables Not Resolving

Symptoms

• Request sent with raw {{variable}} placeholders.

Fix

1. Confirm request has context folder path (saved/loaded in library context).
2. Confirm folder config file exists and contains key.
3. Confirm variable name matches placeholder exactly.

7) Scripts Not Visible/Running

Symptoms

• No script tabs or test execution.

Cause

• Feature flag currently disables script UI and execution.

Notes

• Script fields may still be present in imported/saved docs.

8) Build or Type Errors

Quick Commands

npx tsc --noEmit
npm run build

Use TypeScript output first, then build output, to identify compile vs bundling problems.

9) Windows Cache Permission Warnings

You may see Chromium disk cache warnings in terminal on some systems. These warnings are separate from renderer load failures, but should still be monitored if they correlate with runtime instability.