This repository has been archived on 2026-11-17. You can view files and clone it, but cannot push or open issues or pull requests.
gitgram-ai/gitgram/TROUBLESHOOTING.md
caelum0x 49b183818c Unify gitgram + aitimemachine into the monorepo (de-submodule) and merge vendored engines
Convert gitgram/ and aitimemachine/ from embedded git repos (which showed as
opaque submodule gitlinks on GitHub) into fully-tracked first-party content.

AITM now merges its 7 vendored repos as first-party engines:
- memory: beads (Go task DAG) + context7 (docs SDK), unified into saved_contexts
- git: vendored C git (bundled binary) + gitnexus (in-process code intelligence)
- agentic: a2a (@a2a-js/sdk) + pal (AITM-managed Python subprocess)

Includes the full session's product build: Gitgram web/mobile/backend features,
AITM website/CLI/MCP, the unified memory layer, engine build tooling
(scripts/build-engines.sh, Dockerfile, CI), docs (README, ENGINES.md, ARCHITECTURE.md),
and extensive test suites.

Build artifacts, node_modules, external/, and gemini-cli are gitignored.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-23 14:14:09 +03:00

2.5 KiB

Gitgram Troubleshooting Guide

Common Issues and Solutions

Backend TypeScript Errors

Issue: TypeScript compilation errors with missing type definitions.

Solution:

npm run fix:types

Or manually:

cd backend
npm install --save-dev --legacy-peer-deps @types/compression @types/cookie-parser @types/csurf @types/helmet @types/speakeasy

Port Conflicts

Issue: Port already in use errors.

Solution:

  • Backend (default: 3000): Change in backend/src/config/server.ts
  • Web (default: 3001): Change in web/package.json dev script
  • Mobile (default: 8081): Expo will prompt to use another port

npm-run-all Not Found

Issue: sh: npm-run-all: command not found

Solution: The scripts automatically install it, but you can also:

npm install --save-dev npm-run-all

Peer Dependency Conflicts

Issue: React version conflicts between web (React 18) and mobile (React 19).

Solution: Already handled with --legacy-peer-deps flag. Each project installs independently.

Backend Won't Start

Issue: Backend crashes with TypeScript errors.

Solutions:

  1. Install missing types: npm run fix:types
  2. Check backend/tsconfig.json - strict mode is disabled for compatibility
  3. Ensure all dependencies are installed: npm run install:backend

Database Connection Issues

Issue: Cannot connect to PostgreSQL.

Solution:

  1. Check .env file in backend directory
  2. Ensure PostgreSQL is running
  3. Verify DATABASE_URL is correct
  4. Run migrations: npm run prisma:migrate

Mobile Expo Issues

Issue: Expo won't start or port conflicts.

Solution:

  1. Clear Expo cache: cd mobile && rm -rf .expo
  2. Restart Expo: npm run dev:mobile
  3. Use different port if prompted

Build Errors

Issue: Production builds fail.

Solution:

  1. Clean build artifacts: npm run clean
  2. Reinstall dependencies: npm run install:all
  3. Check for TypeScript errors: cd backend && npm run build

Quick Fixes

Reset Everything

npm run clean:all
npm run install:all
npm run prisma:generate

Fix TypeScript Issues

npm run fix:types
cd backend && npm run build

Check All Services

# Check if ports are available
lsof -i :3000  # Backend
lsof -i :3001  # Web
lsof -i :8081  # Mobile

Getting Help

  1. Check logs in terminal output
  2. Review error messages carefully
  3. Ensure all prerequisites are installed (Node.js >= 18, npm >= 9)
  4. Check project-specific README files