Skip to content

docs: add TROUBLESHOOTING.md troubleshooting manual #3241

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Rish-2006 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add TROUBLESHOOTING.md troubleshooting manual #3241

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions TROUBLESHOOTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# TermUI Troubleshooting Guide

Reference index for diagnosing and fixing common local environment build issues.

## 1. Node Module Version Mismatch
* **Symptom**: Application fails to bundle with explicit missing dependency hooks.
* **Resolution**: Wipe your active module tree and reinstall packages from scratch:
```bash
rm -rf node_modules package-lock.json && npm install
```
Comment on lines +7 to +10

@coderabbitai coderabbitai Bot Jul 28, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== files =="
git ls-files | sed -n '1,120p'
echo "== TROUBLESHOOTING =="
if [ -f TROUBLESHOOTING.md ]; then
  nl -ba TROUBLESHOOTING.md | sed -n '1,80p'
fi

echo "== package manager files =="
for f in package-lock.json npm-shrinkwrap.json pnpm-lock.yaml yarn.lock; do
  echo "--- $f"
  [ -f "$f" ] && wc -l "$f"
done

echo "== lockfile/package scripts relevant =="
if [ -f package.json ]; then
  python3 - <<'PY'
import json
with open('package.json') as f: data=json.load(f)
print(json.dumps({"name": data.get("name"), "scripts": data.get("scripts"), "dependencies": data.get("dependencies"), "devDependencies": data.get("devDependencies")}, indent=2, sort_keys=True))
PY
fi

Repository: Karanjot786/TermUI

Length of output: 5756

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== TROUBLESHOOTING lines 1-30 =="
awk '{printf "%6d\t%s\n",NR,$0} NR<=30' TROUBLESHOOTING.md 2>/dev/null || cat -n TROUBLESHOOTING.md 2>/dev/null | sed -n '1,30p'

echo "== lockfile/package scripts relevant =="
for f in package-lock.json npm-shrinkwrap.json pnpm-lock.yaml yarn.lock package.json; do
  echo "--- $f"
  [ -f "$f" ] && wc -l "$f"
done

if [ -f package.json ]; then
  python3 - <<'PY'
import json
with open('package.json') as f: data=json.load(f)
print(json.dumps({"name": data.get("name"), "scripts": data.get("scripts"), "dependencies": data.get("dependencies"), "devDependencies": data.get("devDependencies")}, indent=2, sort_keys=True))
PY
fi

Repository: Karanjot786/TermUI

Length of output: 3012

Preserve the lockfile during a clean reinstall.

Removing package-lock.json makes npm install resolve a new dependency tree, which can hide the original mismatch and leave local builds unreproducible. Prefer rm -rf node_modules && npm ci; only regenerate the lockfile intentionally when it is stale or invalid.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@TROUBLESHOOTING.md` around lines 7 - 10, Update the clean reinstall command
in the Resolution section of TROUBLESHOOTING.md to remove only node_modules and
use npm ci, preserving package-lock.json. Do not regenerate the lockfile unless
explicitly addressing a stale or invalid lockfile.

Source: MCP tools


## 2. Terminal Resizing Screen Glitches
* **Symptom**: Interface layout blocks break when running inside small viewport sizes.
* **Resolution**: Keep your host terminal window scale above a minimum threshold of 80x24 characters.

## 3. Missing Execution Permissions
* **Symptom**: Local shell scripts fail to run with an access denial alert.
* **Resolution**: Explicitly grant execution rights via your local command shell:
```bash
chmod +x ./scripts/*
```
Loading