FAQ.md

FAQ

Common problems and solutions for OpenCashFlow development.

Setup Issues

Q: "Build failed" when running dotnet build

Symptoms:

• Build errors related to missing packages
• Version mismatch errors

Solutions:

1. Verify .NET SDK version:

   dotnet --version
   # Should be 9.0.300 or higher

2. Restore packages:

   dotnet restore OpenCashFlow.sln

3. Clear NuGet cache:

   dotnet nuget locals all --clear
   dotnet restore

---

Q: Cannot connect to the database

Symptoms:

• Npgsql.NpgsqlException: Failed to connect
• Connection timeout errors

Solutions:

1. Verify PostgreSQL is running:

   # Docker
   docker ps | grep postgres
   
   # Local installation
   pg_isready

2. Check connection string:

   echo $DEFAULT_CONN_STRING

3. Verify database exists:

   psql -U opencashflow -d opencashflow_db -c "SELECT 1"

4. Check firewall/network settings if using remote database

---

Q: HTTPS certificate errors

Symptoms:

• Browser shows "Your connection is not private"
• HttpRequestException: The SSL connection could not be established

Solutions:

1. Trust development certificates:

   dotnet dev-certs https --trust

2. If that fails, clean and regenerate:

   dotnet dev-certs https --clean
   dotnet dev-certs https --trust

3. On macOS, you may need to manually trust in Keychain Access

---

Q: Port already in use

Symptoms:

• System.IO.IOException: Failed to bind to address
• Address already in use

Solutions:

1. Find process using the port:

   # macOS/Linux
   lsof -i :7001
   
   # Windows
   netstat -ano | findstr :7001

2. Kill the process:

   # macOS/Linux
   kill -9 <PID>
   
   # Windows
   taskkill /PID <PID> /F

3. Or change port in launchSettings.json:

   "applicationUrl": "https://localhost:7010;http://localhost:5010"

---

Database Issues

Q: Migration fails with "Unable to create DbContext"

Symptoms:

• EF Core tools cannot instantiate the context
• Missing connection string errors

Solutions:

1. Set environment variable:

   export DEFAULT_CONN_STRING="Host=localhost;Database=opencashflow_db;..."

2. Ensure API project has appsettings.json with connection string

3. Build the projects first:

   dotnet build src/OpenCashFlow.API/OpenCashFlow.API.csproj

---

Q: "Migration already applied" but schema is wrong

Symptoms:

• Database has old schema
• __EFMigrationsHistory shows migration applied

Solutions:

1. Check migration history:

   SELECT * FROM "__EFMigrationsHistory";

2. If migration was partially applied, reset:

   # Remove from history (carefully)
   DELETE FROM "__EFMigrationsHistory" WHERE "MigrationId" = '20240124_AddNewFeature';
   
   # Reapply
   dotnet ef database update

3. For fresh start (development only):

   dotnet ef database drop --force
   dotnet ef database update

---

Q: Concurrency exception on CashBalance

Symptoms:

• DbUpdateConcurrencyException when updating balance
• Optimistic locking failures

Solutions:

This is expected behavior for concurrent updates. Handle it:

try
{
    await _context.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
    // Retry with fresh data
    await _context.Entry(balance).ReloadAsync();
    balance.Balance += delta;
    await _context.SaveChangesAsync();
}

---

Authentication Issues

Q: JWT token is invalid or expired

Symptoms:

• 401 Unauthorized responses
• "Token expired" errors

Solutions:

1. Check token expiration (default 15 minutes):

   // Decode token (client-side debugging)
   const payload = JSON.parse(atob(token.split('.')[1]));
   console.log(new Date(payload.exp * 1000));

2. Implement refresh token flow:

   if (response.status === 401) {
       await refreshToken();
       // Retry request
   }

3. Verify JWT configuration matches between App and API

---

Q: CORS errors in browser

Symptoms:

• Access-Control-Allow-Origin header missing
• Preflight request fails

Solutions:

1. Verify CORS configuration:

   echo $CORS__ALLOWEDORIGINS__0

2. Ensure exact URL match (including protocol and port):

   # Correct
   CORS__ALLOWEDORIGINS__0=https://localhost:7001
   
   # Wrong (missing port, different protocol)
   CORS__ALLOWEDORIGINS__0=http://localhost

3. Check CORS middleware order in Program.cs:

   app.UseCors();  // Must be before UseAuthorization
   app.UseAuthorization();

---

Q: Cookie not being sent with requests

Symptoms:

• Authentication works but subsequent requests fail
• Cookie visible in browser but not sent

Solutions:

1. Ensure credentials: 'include' in fetch:

   fetch(url, {
       credentials: 'include'
   });

2. Check SameSite settings match domain configuration:

   options.Cookie.SameSite = SameSiteMode.None;  // For cross-site
   options.Cookie.SameSite = SameSiteMode.Lax;   // For same-site

3. Verify cookie domain setting

---

API Issues

Q: API returns 500 error without details

Symptoms:

• Generic error message in production
• No stack trace visible

Solutions:

1. Check Sentry for detailed error

2. Check application logs:

   tail -f Logs/log-*.txt

3. In development, enable detailed errors:

   if (app.Environment.IsDevelopment())
   {
       app.UseDeveloperExceptionPage();
   }

---

Q: API returns 403 Forbidden

Symptoms:

• User is authenticated but access denied
• Subscription middleware blocking

Solutions:

1. Check subscription status:

   SELECT * FROM "Company_Subscription"
   WHERE "TenantID" = 'your-tenant-id';

2. Verify user permissions:

   // Check user has required permission
   var permissions = User.Claims
       .Where(c => c.Type == "permission")
       .Select(c => c.Value);

3. Check if tenant ID in token matches resource

---

UI Issues

Q: Tabler styles not loading

Symptoms:

• Page appears unstyled
• 404 errors for CSS files

Solutions:

1. Verify files exist in wwwroot/vendor/tabler/

2. Check static files middleware:

   app.UseStaticFiles();  // Must be called

3. Clear browser cache or hard refresh (Ctrl+Shift+R)

---

Q: SignalR connection fails

Symptoms:

• Real-time updates not working
• WebSocket connection errors

Solutions:

1. Check SignalR hub is mapped:

   app.MapHub<PaymentHub>("/hubs/payment");

2. Verify CORS allows SignalR:

   policy.WithOrigins(origins)
         .AllowCredentials();  // Required for SignalR

3. Check browser console for specific errors

---

Q: Forms not submitting / JavaScript errors

Symptoms:

• Form submit does nothing
• Console shows JavaScript errors

Solutions:

1. Check browser console (F12) for errors

2. Verify jQuery is loaded before custom scripts:

   <script src="~/libs/jquery/jquery.min.js"></script>
   <script src="~/js/site.js"></script>

3. Check for syntax errors in JavaScript files

---

Performance Issues

Q: Slow database queries

Symptoms:

• API responses take several seconds
• High CPU usage on database server

Solutions:

1. Enable query logging temporarily:

   "Logging": {
       "LogLevel": {
           "Microsoft.EntityFrameworkCore.Database.Command": "Information"
       }
   }

2. Check for missing indexes:

   EXPLAIN ANALYZE SELECT * FROM "Payments"
   WHERE "TenantID" = '...' AND "PaymentDate" > '...';

3. Add appropriate indexes:

   modelBuilder.Entity<Payment>()
       .HasIndex(p => new { p.TenantID, p.PaymentDate });

---

Q: Memory usage keeps growing

Symptoms:

• Application memory increases over time
• Eventually OutOfMemoryException

Solutions:

1. Check for missing Dispose() calls on DbContext:

   // Bad - context never disposed
   var context = new ApplicationDbContext();
   
   // Good - using DI with scoped lifetime
   services.AddDbContext<ApplicationDbContext>(ServiceLifetime.Scoped);

2. Profile memory usage:

   dotnet-counters monitor --process-id <PID>

3. Check for event handler leaks

---

Deployment Issues

Q: GitHub Actions build fails

Symptoms:

• CI workflow shows red X
• Build or test step fails

Solutions:

1. Check workflow logs in GitHub Actions tab

2. Run same commands locally:

   dotnet restore
   dotnet build --no-restore
   dotnet test --no-build

3. Ensure all test dependencies are available

---

Q: Docker build fails

Symptoms:

• docker build exits with error
• Missing files or packages

Solutions:

1. Check Dockerfile paths are correct

2. Ensure .dockerignore isn't excluding needed files

3. Build with verbose output:

   docker build --progress=plain -t opencashflow .

---

Getting Help

If your issue isn't covered here:

1. Search existing GitHub Issues
2. Check the Discussions
3. Review the detailed documentation in this wiki
4. Create a new issue with:
   • Steps to reproduce
   • Expected vs actual behavior
   • Relevant logs/error messages
   • Environment details (OS, .NET version, etc.)