Troubleshooting
Troubleshooting philosophy
FridayLocalAI is being built with a bias toward explicit contracts, regression awareness, and stable behavior. Troubleshooting should follow that same pattern: identify the layer that failed, verify the expected contract, and correct the smallest broken part without reinventing the entire machine in a panic.
In other words: fewer exorcisms, more diagnostics.
Common problem areas
- Local model runtime unavailable
- Configuration mismatch between services
- Database or persistence failures
- Conversation hydration or UI rendering problems
- File or artifact handling errors
- Memory scope read/write inconsistency
What to verify first
- Is the required service actually running?
- Is the application pointing to the correct path or database?
- Did a recent change violate an existing contract?
- Is the issue local to one page, one feature, or one data flow?
- Can the issue be reproduced consistently?
Suggested diagnostic method
- Identify the failing subsystem: UI, backend, model runtime, storage, or knowledge path.
- Compare current behavior to the last known good behavior.
- Inspect the immediate contract: API payload, schema assumption, route, file path, or runtime dependency.
- Correct one axis at a time rather than stacking random changes.
- Verify the fix without introducing regression into adjacent features.
Future operational hardening
FridayLocalAI’s roadmap already includes work related to conversation stability, host-drive access, artifact generation, and broader system capability expansion. As those areas mature, this troubleshooting section will expand to include operational runbooks, health checks, service validation guidance, and recovery procedures for key subsystems.
For the broader platform context, continue to Architecture or Documentation.