-
Notifications
You must be signed in to change notification settings - Fork 0
Troubleshooting FAQ
hitchhiker edited this page Feb 4, 2026
·
4 revisions
Solutions to common issues and frequently asked questions.
# Check job queue status
curl http://localhost:8765/status/jobs
# If stuck:
1. Check repository is connected
2. Check webhook is configured in GitHub/GitLab
3. Check file isn't in exclude patterns (fold/project.toml)
4. Verify file < 100KB
# Manually trigger sync
curl -X POST http://localhost:8765/api/projects/my-app/repositories/{id}/sync# Fold stores memories as markdown files in fold/
# If corrupted, rebuild from database:
1. Delete fold/ directory
rm -rf fold/
2. Restart server
cargo run
3. Re-index repositories
curl -X POST http://localhost:8765/api/projects/my-app/sync
# Or restore from git
git checkout fold/# Check if memories are indexed
curl http://localhost:8765/api/projects/my-app/memories?limit=1
# If empty:
1. Repository may not be connected
2. Files may not match include patterns
3. May need to trigger indexing
# Force reindex
curl -X POST http://localhost:8765/api/projects/my-app/repositories/{id}/sync
# Try simpler search terms
curl -X POST http://localhost:8765/api/projects/my-app/search \
-H "Authorization: Bearer $TOKEN" \
-d '{"query": "auth", "limit": 5}'# Decay weights recent memories heavily
# If all results are old:
1. Check DECAY_HALF_LIFE_DAYS setting (default: 30)
2. Check DECAY_STRENGTH_WEIGHT (default: 0.3)
3. Try with include_decay: false to test semantic-only search
# Disable decay entirely
curl -X POST http://localhost:8765/api/projects/my-app/search \
-d '{"query": "...", "include_decay": false}'# Error: "permission denied while trying to connect to Docker daemon"
# Solution: Add your user to docker group
sudo usermod -aG docker $USER
newgrp docker
# Or use sudo
sudo docker-compose up -d# Find what's using the port
lsof -i :8765
# Change Fold port in docker-compose.yml
# From: "8765:8765"
# To: "9000:8765"
# Or in .env for local dev
PORT=9000# Make sure Qdrant is running
docker ps | grep qdrant
# If not, start it
docker run -p 6334:6334 qdrant/qdrant
# Check connection
curl http://localhost:6334/health# Error: "database is locked"
# This usually means multiple processes are accessing the DB
# Check running processes
ps aux | grep fold
# If corrupted, backup and delete
mv data/fold.db data/fold.db.bak
# Fold will recreate the schema on startup
# For production, migrate to PostgreSQL
# See: Configuration > Database Setup# Error: 401 when trying to bootstrap admin
# Check:
1. Token is set in .env
ADMIN_BOOTSTRAP_TOKEN=your-token
2. Token in bootstrap request matches
curl -X POST http://localhost:8765/auth/bootstrap \
-d '{"token": "your-token", ...}'
3. First admin hasn't been created yet
(You can only bootstrap once)# Create a new token
curl -X POST http://localhost:8765/me/tokens \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "new-token"}'
# Verify token format (should start with "fold_")
echo $YOUR_TOKEN
# Test token
curl http://localhost:8765/auth/me \
-H "Authorization: Bearer $YOUR_TOKEN"
# Should return 200 with user info# Check provider configuration in .env
AUTH_PROVIDER_GOOGLE_TYPE=oidc
AUTH_PROVIDER_GOOGLE_DISPLAY_NAME=Google
AUTH_PROVIDER_GOOGLE_ISSUER=https://accounts.google.com
AUTH_PROVIDER_GOOGLE_CLIENT_ID=xxx
AUTH_PROVIDER_GOOGLE_CLIENT_SECRET=xxx
# Verify OIDC discovery endpoint
curl https://accounts.google.com/.well-known/openid-configuration
# Check Fold logs
docker-compose logs fold | grep -i auth
# Make sure PUBLIC_URL is correct (for redirects)
PUBLIC_URL=http://localhost:8765 # for local dev
PUBLIC_URL=https://fold.example.com # for production# Check webhook registration
curl http://localhost:8765/projects/proj_abc/repositories \
-H "Authorization: Bearer YOUR_TOKEN"
# Verify GitHub webhook exists
# Go to: https://github.com/owner/repo/settings/hooks
# Check webhook logs
curl http://localhost:8765/projects/proj_abc/repositories/repo_123/webhook-logs \
-H "Authorization: Bearer YOUR_TOKEN"
# Manually trigger a test
# GitHub UI: Click "Test" on the webhook
# Check Fold logs
docker-compose logs fold | grep webhook# Check job status
curl http://localhost:8765/status/jobs \
-H "Authorization: Bearer YOUR_TOKEN"
# Kill a stuck job
curl -X DELETE http://localhost:8765/status/jobs/job_abc123 \
-H "Authorization: Bearer YOUR_TOKEN"
# Restart indexing
curl -X POST http://localhost:8765/projects/proj_abc/repositories/repo_123/reindex \
-H "Authorization: Bearer YOUR_TOKEN"
# For very large repos, increase timeout
# In docker-compose.yml:
# environment:
# - WEBHOOK_TIMEOUT=600 # 10 minutes# Generate new token
# https://github.com/settings/tokens
# Update repo connection
curl -X PUT http://localhost:8765/projects/proj_abc/repositories/repo_123 \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"access_token": "ghp_new_token_here"
}'# Check if memories are indexed
curl http://localhost:8765/projects/proj_abc/memories \
-H "Authorization: Bearer YOUR_TOKEN"
# Try a simpler query
# Bad: "jwt token expiration session validation"
# Good: "jwt" or "how does authentication work"
# Check memory content exists
curl http://localhost:8765/projects/proj_abc/memories/mem_abc123 \
-H "Authorization: Bearer YOUR_TOKEN"
# Verify Qdrant has vectors
curl http://localhost:6334/collections/proj_abc/points/count
# Re-embed a memory
curl -X POST http://localhost:8765/projects/proj_abc/memories/mem_abc123/re-embed \
-H "Authorization: Bearer YOUR_TOKEN"# Check query performance
# Time a search
time curl -X POST http://localhost:8765/projects/proj_abc/search \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{"query": "auth", "limit": 10}'
# If > 1 second, optimization needed:
# 1. Check Qdrant is healthy
curl http://localhost:6334/health
# 2. Reduce search limit
# Instead of limit: 1000, use limit: 10
# 3. Check database indexes
# See: Deployment > Performance Tuning
# 4. Scale Qdrant
# See: Deployment > Scaling Strategies# Check memory exists
curl http://localhost:8765/projects/proj_abc/memories/mem_abc123 \
-H "Authorization: Bearer YOUR_TOKEN"
# Check embedding status
# Memory should have "embedding_vector" field
# Re-embed manually
curl -X POST http://localhost:8765/projects/proj_abc/memories/mem_abc123/re-embed \
-H "Authorization: Bearer YOUR_TOKEN"
# Check LLM is working
curl -X POST http://localhost:8765/health/llm \
-H "Authorization: Bearer YOUR_TOKEN"# Verify Fold MCP endpoint is working
curl -X POST http://localhost:8765/mcp \
-H "Authorization: Bearer fold_your_token" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "project_list", "params": {}}'
# Check Claude Code config
# ~/.claude/settings.json should have:
{
"mcpServers": {
"fold": {
"url": "http://localhost:8765/mcp",
"headers": {
"Authorization": "Bearer fold_your_token"
}
}
}
}
# Restart Claude Code
# Tools should appear in the sidebar
# Enable MCP debug logging
# .env
MCP_LOG_LEVEL=debug# Register your workspace with Fold
curl -X POST http://localhost:8765/projects/proj_abc/workspace \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"local_root": "/Users/you/projects/myapp",
"repository_id": "repo_123"
}'
# Now search results include local_path
{
"file_path": "src/auth.rs",
"local_path": "/Users/you/projects/myapp/src/auth.rs"
}
# Claude Code can click to open these files# The token's user might not have access to the project
# Check user's project access
curl http://localhost:8765/me \
-H "Authorization: Bearer fold_your_token"
# Grant user access to project
# (Done through project membership, not token settings)
curl -X POST http://localhost:8765/api/projects/my-project/members \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"user_id": "user_id", "role": "member"}'# Fold using too much RAM?
# Check what's consuming memory
docker stats fold
# Common causes:
1. Large embedding model loaded
- Use smaller model: all-MiniLM-L6-v2
2. Too many memories in RAM
- Reduce cache size in .env
CACHE_MAX_SIZE=500MB
3. Qdrant needs more memory
- Increase Qdrant container memory
- In docker-compose.yml: memory: 4g
4. Unindexed files accumulating
- Check job queue
curl http://localhost:8765/status/jobs# Check what's running
docker-compose logs fold | tail -50
# Common causes:
1. Indexing a huge repository
- Let it finish or increase timeout
- Monitor job progress: curl http://localhost:8765/status/jobs/job_id
2. Embedding calculation
- Reduce batch size
- Switch to smaller embedding model
3. Vector search optimization running
- Wait for it to complete
- Check Qdrant logs: docker-compose logs qdrant# Check database size
du -sh data/fold.db
# Vacuum to reclaim space (SQLite)
sqlite3 data/fold.db "VACUUM;"
# Or in production (PostgreSQL)
psql -d fold -c "VACUUM ANALYZE;"
# Archive old memories if not needed
curl -X DELETE http://localhost:8765/projects/proj_abc/memories/mem_old123 \
-H "Authorization: Bearer YOUR_TOKEN"# Error: 401 on webhook endpoint
# Check webhook secret
curl http://localhost:8765/projects/proj_abc/repositories/repo_123 \
-H "Authorization: Bearer YOUR_TOKEN"
# Should have "webhook_secret" field
# Verify GitHub is sending correct signature
# In GitHub webhook logs, check X-Hub-Signature-256 header
# Recreate webhook
curl -X DELETE http://localhost:8765/projects/proj_abc/repositories/repo_123/webhook \
-H "Authorization: Bearer YOUR_TOKEN"
curl -X POST http://localhost:8765/projects/proj_abc/repositories/repo_123/webhook \
-H "Authorization: Bearer YOUR_TOKEN"# Check webhook handler logs
docker-compose logs fold | grep "webhook_received"
# Increase timeout
# docker-compose.yml
environment:
- WEBHOOK_TIMEOUT=600 # 10 minutes
# Check if indexing is backed up
curl http://localhost:8765/status/jobs \
-H "Authorization: Bearer YOUR_TOKEN"
# Scale up workers
docker-compose up -d --scale fold=3# Check which provider is configured
# .env should have at least one:
GOOGLE_API_KEY=...
OPENROUTER_API_KEY=...
OPENAI_API_KEY=...
# Test the primary provider
curl -X POST http://localhost:8765/health/llm/test \
-H "Authorization: Bearer YOUR_TOKEN"
# Check logs
docker-compose logs fold | grep -i llm
# If Gemini fails, fallback to OpenRouter
# If both fail, error is returned
# Verify API keys are correct
# Try curl directly to the provider:
curl https://generativelanguage.googleapis.com/v1/models \
-H "x-goog-api-key: $GOOGLE_API_KEY"# fastembed downloads model on first run (~90MB)
# Check progress
docker-compose logs fold | grep -i embedding
# If stuck, restart
docker-compose down
docker-compose up -d
# Or pre-download model
docker exec fold /app/fold download-embeddingsNo. Fold indexes Git; it doesn't replace it. Your source of truth is always Git. Fold adds semantic memory on top.
Minimal. Local embeddings = free. LLM costs vary:
- Gemini: Free tier available, $0.05/1M tokens after
- OpenRouter: Free models available
- OpenAI: ~$0.02-0.10 per 1M tokens
For small teams: $0-50/month total.
Mostly. With local embeddings, yes. If you use cloud LLMs (Gemini, OpenAI), you need internet for LLM calls but can still search locally-embedded memories.
Yes.
curl -X DELETE http://localhost:8765/projects/proj_abc/memories/mem_xyz \
-H "Authorization: Bearer YOUR_TOKEN"Deletion is permanent (but not immediately purged from vector DB due to caching).
Possible.
- Memories are stored in SQLite (portable)
- Vectors can be exported from Qdrant
- Memory links/graph are in the database
- Session notes are in plaintext in the database
Export via:
sqlite3 data/fold.db ".dump memories" > memories.sqlYes. Each project is isolated. Access control is managed through project membership (direct user or group). Each user's access is determined by their membership, and tokens inherit this access.
Yes, with caveats:
- All data stored locally (SQLite + Qdrant)
- Tokens are required for API access
- OIDC auth prevents unauthorized access
- If using cloud LLM, summaries are sent to the provider (can be configured to use local LLM only)
For maximum security:
# Use only local embeddings and no cloud LLM
EMBEDDING_PROVIDER=local # fastembed
LLM_PROVIDER=local # (not available yet, but planned)# Pull latest code
git pull origin main
# Update .env if needed
# Check .env.example for new variables
# Rebuild Docker image
docker-compose down
docker-compose build --no-cache
docker-compose up -d# Check if path hash is being computed correctly
# This usually means:
1. Path normalisation issue
- Ensure paths use forward slashes
- Check project slug is consistent
2. Files are being modified on push
- Git hooks modifying files
- Check git config: git config --local -l
3. Webhook is sending incorrect data
- Test webhook manually in GitHub UI# .env
RUST_LOG=debug
MCP_LOG_LEVEL=debug
DATABASE_LOG_LEVEL=debug
# Then check logs
docker-compose logs fold -fecho "=== Versions ==="
docker-compose --version
docker --version
echo "=== Fold Status ==="
curl http://localhost:8765/health
echo "=== Qdrant Status ==="
curl http://localhost:6334/health
echo "=== Services Running ==="
docker-compose ps
echo "=== Recent Logs (last 100 lines) ==="
docker-compose logs fold --tail 100
echo "=== Database Size ==="
du -sh data/fold.db- Collect debug info (above)
- Describe steps to reproduce
- Include relevant error messages/logs
- Report at: https://github.com/Generation-One/fold/issues
- Advanced-Topics — For power users
- Configuration — Detailed setup
- Deployment-Operations — Production operations