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>
2.5 KiB
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.jsondev 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:
- Install missing types:
npm run fix:types - Check
backend/tsconfig.json- strict mode is disabled for compatibility - Ensure all dependencies are installed:
npm run install:backend
Database Connection Issues
Issue: Cannot connect to PostgreSQL.
Solution:
- Check
.envfile in backend directory - Ensure PostgreSQL is running
- Verify
DATABASE_URLis correct - Run migrations:
npm run prisma:migrate
Mobile Expo Issues
Issue: Expo won't start or port conflicts.
Solution:
- Clear Expo cache:
cd mobile && rm -rf .expo - Restart Expo:
npm run dev:mobile - Use different port if prompted
Build Errors
Issue: Production builds fail.
Solution:
- Clean build artifacts:
npm run clean - Reinstall dependencies:
npm run install:all - 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
- Check logs in terminal output
- Review error messages carefully
- Ensure all prerequisites are installed (Node.js >= 18, npm >= 9)
- Check project-specific README files