Troubleshooting
Troubleshooting
Find the failing layer, then apply the smallest safe fix.
Most OpenFolks failures come from one of four layers: the desktop app, a local engine CLI, a connected service, or a computer backend.
Startup and ports
App will not open, local server is down, or a port is taken.
Engines
CLI missing, model unavailable, sign-in failure, or reconnect loop.
Connected apps
OAuth finishes but tools do not appear, or an account vanishes.
Updates
Download spins, restart does nothing, or the new version does not launch.
Useful evidence
Before opening an issue, record:
- OpenFolks version and operating system
- selected engine and model
- the exact visible error, not only “it failed”
- whether the same CLI works in a terminal
- whether restarting only the affected task changes the result
Never post API keys, OAuth callback URLs, bearer tokens, or the contents of secure credential files.