Overview
This guide covers common issues, error messages, and solutions based on real engineering challenges documented in the ENGINEERING_LOG.md.InfluxDB Connection Issues
Error: 401 Unauthorized
Error: 401 Unauthorized
Error: Connection refused
Error: Connection refused
-
Verify
INFLUX_URLmatches your InfluxDB Cloud region: -
Test connectivity:
- Check firewall/VPN settings blocking port 443
Error: Query returned 0 results despite data existing
Error: Query returned 0 results despite data existing
pivot() (see ENGINEERING_LOG Phase 2).Solution:WRONG:pivot() when using pivoted column names.Error: Data available but queries return empty
Error: Data available but queries return empty
/write response.Model Loading Errors
Error: No module named 'sklearn'
Error: No module named 'sklearn'
Error: name 'np' is not defined (Type Annotations)
Error: name 'np' is not defined (Type Annotations)
numpy is lazy-loaded (see ENGINEERING_LOG Phase 18).Solution:Add this to the top of ML modules:from __future__ import annotations defers annotation evaluation (PEP 563).Error: Model file not found
Error: Model file not found
-
Check if models directory exists:
-
Calibrate the system to train models:
-
Or retrain manually:
Warning: Model trained on X features, got Y
Warning: Model trained on X features, got Y
-
Delete old models:
-
Retrain from scratch:
CORS Issues
Error: CORS policy blocked (Port 3001)
Error: CORS policy blocked (Port 3001)
backend/api/main.py:Error: Method PUT not allowed
Error: Method PUT not allowed
PUT not in allow_methods (see ENGINEERING_LOG Phase 20).Solution:Update CORS config:Render Free Tier Issues
Error: 503 Service Unavailable (Cold Start)
Error: 503 Service Unavailable (Cold Start)
Error: Container killed during startup
Error: Container killed during startup
sklearn, numpy, pandas) at module level exceed 512MB RAM limit (see ENGINEERING_LOG Phase 18).Solution:Lazy-load ML dependencies:Health check timeout
Health check timeout
/health endpoint loads heavy ML modules, exceeding health check timeout.Solution:Use a lightweight /ping endpoint for health checks:- Open Render Dashboard → Service Settings
- Health Check Path:
/ping - Save
Windows Development Issues
Error: Vercel Error 126 (Permission Denied)
Error: Vercel Error 126 (Permission Denied)
node_modules/ committed to Git (see README).Solution:-
Add
node_modules/to.gitignore: -
Remove from Git history:
- Vercel will install dependencies on Linux during build
Error: 'venv\Scripts\activate' not recognized
Error: 'venv\Scripts\activate' not recognized
Data Quality Issues
False positives: Healthy data flagged as anomalous
False positives: Healthy data flagged as anomalous
- Overly sensitive range checks (10% tolerance too strict)
- Majority aggregation threshold too low (15% anomalous points)
- No event debouncing (single-tick transitions)
system_routes.py and integration_routes.py:database.py:EventEngine:Health drops to 66% on startup with no fault
Health drops to 66% on startup with no fault
assessor.py:Jitter faults not detected
Jitter faults not detected
-
Check model file exists:
-
If missing, retrain:
-
Restart backend to load batch model:
- v3 has std and peak_to_peak features
- v2 only has mean (blind to variance)
Chart Visualization Issues
Chart line floats in the air on startup
Chart line floats in the air on startup
connectNulls=true connects single point to empty space (see ENGINEERING_LOG Phase 16).Solution:Only render lines when ≥2 points exist:Normal sensor noise looks like major anomalies
Normal sensor noise looks like major anomalies
Chart X-axis grows instead of sliding window
Chart X-axis grows instead of sliding window
domain={['dataMin', 'dataMax']} grows with data (see ENGINEERING_LOG Phase 16).Solution:Hard-code 60s right-anchored window:Report Generation Issues
Excel Anomaly_Score column always empty
Excel Anomaly_Score column always empty
Anomaly_Score column.Cause: Anomaly scores only computed at ingestion time, not at report generation (see ENGINEERING_LOG Phase 19).Solution:Compute range-check scores in generator.py during report creation:Operator logs show test gibberish (asyfkk)
Operator logs show test gibberish (asyfkk)
ReportLab error: 'Canvas' object has no attribute 'stroke'
ReportLab error: 'Canvas' object has no attribute 'stroke'
canvas.stroke() (see ENGINEERING_LOG Phase 10).Solution:Use drawPath() for arcs:Environment Configuration
Warning: INFLUX_TOKEN not found (but it exists in .env)
Warning: INFLUX_TOKEN not found (but it exists in .env)
.env file has INFLUX_TOKEN=...Cause: Validation checks os.environ instead of settings object (see ENGINEERING_LOG Phase 20).Solution:Check settings object, not raw env:requirements.txt lists packages not installed
requirements.txt lists packages not installed
requirements.txt manually edited with wrong versions.Solution:Regenerate from actual environment:Getting Help
If your issue isn’t covered here:Check Engineering Log
Open GitHub Issue
- Error message and full stack trace
- Steps to reproduce
- Environment (Docker/systemd, OS, Python version)
- Relevant logs