Known Bugs & Issues¶
Track bugs found during development and deployment. Copy these to GitHub Issues when ready.
High Priority 🔴¶
#1: create_default_users.py Missing Timestamps¶
Status: Open Found: MI-20 deployment (Dec 1, 2025) Impact: Login fails on fresh deployments
Description:
The scripts/create_default_users.py script creates users without setting created_at and updated_at timestamps. When users try to login, Pydantic validation fails with:
Workaround: Manually update timestamps after running the script:
import duckdb
from datetime import datetime
conn = duckdb.connect('db/pocket.db')
conn.execute("UPDATE user SET created_at = ?, updated_at = ? WHERE created_at IS NULL",
[datetime.utcnow(), datetime.utcnow()])
conn.close()
Fix:
Update scripts/create_default_users.py to include timestamps:
from datetime import datetime
now = datetime.utcnow()
# Add to INSERT statement: created_at, updated_at
# Add to VALUES: now, now
Files:
- scripts/create_default_users.py
#2: Port Conflicts During Service Restart¶
Status: Open Found: MI-20 deployment Impact: Services fail to start, restart loops
Description: When restarting services, processes don't always release ports cleanly. Multiple instances compete for the same ports (32300/32301), causing "Address already in use" errors.
Root Causes: - Systemd auto-restart happens before ports are freed - Background processes stick around after crashes - No port availability check before starting
Workaround:
Use restart_services.sh script that:
1. Stops systemd services
2. Kills all processes on ports (twice)
3. Waits for ports to clear
4. Starts services in order
Fix: Application deployment module should: - Check port availability before starting - Force-kill existing processes on tenant ports - Add retry logic with backoff - Validate service started successfully
Files:
- Deployment automation (to be built)
- restart_services.sh (workaround)
Medium Priority 🟡¶
#3: WinRed Pages Timeout During AI Analysis¶
Status: Open (Known Limitation) Found: MI-20 theme analysis Impact: Can't analyze some campaign websites
Description: Heavy JavaScript sites (especially WinRed donation pages) timeout during Playwright screenshot capture:
Affected Sites: - WinRed campaign pages - ActBlue pages - Sites with heavy tracking scripts
Workarounds: 1. Use simpler campaign pages for analysis 2. Manually apply appropriate theme colors 3. Use test pages that load faster
Fixes: 1. Increase timeout to 60-90 seconds 2. Use 'load' instead of 'networkidle' wait strategy 3. Add retry with different wait strategies 4. Fallback to manual theme selection
Files:
- agents/screenshot.py - ScreenshotAgent class
- agents/claude_client.py - Timeout configuration
#4: Browser Caching Shows Old Branding¶
Status: Open Found: MI-20 branding update Impact: User confusion, looks like update didn't work
Description: When updating logos, colors, or branding, browsers aggressively cache static assets. Users see old branding even after updates are applied.
Workarounds: - Hard refresh (Ctrl+Shift+R) - Incognito/private browsing - Clear browser cache
Fixes:
1. Add version query params to static URLs: /static/logo.png?v=timestamp
2. Set proper Cache-Control headers in NGINX
3. Use content-hash based filenames
4. Add cache-busting on deployment
Files:
- NGINX templates (add headers)
- src/app/templates/layout.html (add version params)
Low Priority 🟢¶
#5: DNS Zone File Formatting¶
Status: Fixed (Dec 1, 2025) Impact: DNS records don't resolve
Description: When adding DNS records via API, newlines were missing causing records to concatenate:
Fix Applied:
Updated api/routes/deploy.py to add proper newlines:
Status: ✅ Resolved in commit 0603b22
#6: NGINX Directory Permissions¶
Status: Fixed (Dec 1, 2025) Impact: API can't write config files
Description:
/etc/nginx/sites-nominate/ created with root ownership, API couldn't write configs.
Fix Applied:
Status: ✅ Resolved Note: Deployment automation should create directory with proper permissions
Feature Requests 💡¶
FR#1: Wildcard DNS Support¶
Priority: Low
Description: Add *.nominate.ai → 104.11.127.142 to eliminate zone file updates
Pros: - No DNS management needed - Instant subdomain availability - Simpler deployment
Cons: - Any typo subdomain resolves - Potential security consideration - Less explicit control
Decision: Stick with explicit A records for now
FR#2: GitHub Fork Per Tenant¶
Priority: High Description: Create GitHub fork for each tenant instead of copying code
Benefits: - Version control per tenant - Pull upstream improvements - Tenant-specific customizations tracked - Easy rollback
Implementation: - GitHub API integration - Fork creation endpoint - Clone instead of copy - Update management
Planned for: Next iteration after app work
FR#3: Health Monitoring Dashboard¶
Priority: Medium Description: Automated health checks with alerting
Features: - Periodic service health checks - Auto-restart crashed services - Resource monitoring (CPU, memory, disk) - Response time tracking - Alert on failures - Dashboard view in Tenant Manager
Planned for: After deployment automation complete
Bug Tracking Workflow¶
To create a GitHub Issue:
- Via GitHub Web:
- Go to https://github.com/Nominate-AI/cbtenant/issues
- Click "New issue"
-
Use templates below
-
Via GitHub CLI:
-
Issue Template:
## Description [What's broken] ## Steps to Reproduce 1. Step one 2. Step two 3. See error ## Expected Behavior [What should happen] ## Actual Behavior [What actually happens] ## Impact [Who/what is affected] ## Workaround [Temporary fix if available] ## Suggested Fix [How to resolve] ## Files Affected - file1.py - file2.py
Labels:
- bug - Something isn't working
- enhancement - New feature request
- high-priority - Needs immediate attention
- deployment - Related to tenant deployment
- ai-integration - AI/Claude features
- infrastructure - DNS/NGINX/SSL
- documentation - Docs improvements
Current Bug Status¶
Open: 4 bugs (2 high, 2 medium) Fixed: 2 bugs Feature Requests: 3
Next Steps: 1. Enable GitHub Issues on the repository 2. Create issues from this list 3. Prioritize and assign 4. Track fixes with commit references