Use this page as a short diagnostic path. Public Alpha builds and provider integrations vary by platform, credentials, network, and local model configuration.
The application does not start
Windows
1. Confirm that you extracted the complete Windows x64 package. 2. Install the Microsoft Visual C++ Redistributable for Visual Studio 2022. 3. Keep the executable beside its bundled Qt DLLs and platforms directory. 4. If Windows reports a missing DLL, record the exact filename before changing anything.
Do not start with administrator privileges. That can hide a permissions or path problem and may write configuration into an unexpected profile.
Linux
1. Confirm the AppImage is executable: chmod +x NeuralScio-*.AppImage. 2. Check the package's documented system-library requirements. 3. If the AppImage runtime fails, run it from a terminal and keep the complete error output.
macOS does not currently have a verified Public Alpha download artifact. A source-build path may exist, but it is not a parity-tested release route.
The window is blank or crashes during startup
First retry with software rendering if that option is available in the current build. Then update the graphics driver and capture the startup log. Do not delete the configuration directory before making a backup.
If the configuration is suspected, use the current build's reset-to-default action. If no reset action is available, close the app, copy the configuration directory to a safe backup location, and only then rename the original directory. Renaming is reversible; deletion is not.
Qt platform plugin or missing DLL errors
The executable must remain with its packaged Qt runtime and platforms folder. Re-extract a fresh copy of the same package before copying DLLs from another Qt installation. Mixing Qt versions can create a different startup failure.
Search returns nothing or times out
Check these in order:
1. Confirm that network access is available for external scholarly providers. 2. Try one provider and a simpler query. 3. Widen date filters and remove restrictive field filters. 4. Check whether the selected provider needs an API key or has a rate limit. 5. Retry after noting the provider name, query, and approximate time.
Metadata, full text, PDF access, and rate limits differ by provider. Duplicate records can still occur when two sources describe the same work differently.
A PDF will not open or render
Confirm that the file opens in another reader and that the current user can read it. Re-download a corrupted file and retry from a local path. If only GPU rendering fails, use software rendering and record the graphics hardware and driver version.
Do not clear the entire library or cache as a first step. Saved files, annotations, and cached reading state may be valuable local data.
Local AI or the worker is unavailable
1. Confirm that the model path exists and points to a compatible GGUF file. 2. Try a smaller model or the CPU backend. 3. Check available RAM and VRAM. 4. Confirm that NeuralScioAI can start beside the desktop executable. 5. For an Ollama-compatible route, confirm that the runtime and configured endpoint are reachable.
Cloud and BYOK routes have separate credentials and network requirements. A local model path and a managed cloud model are not interchangeable.
Sync or account data looks wrong
Treat the local library and saved PDFs as important until the account state is understood. Reopen the current account/sync surface, verify the source device still has the item, and avoid signing out repeatedly while investigating. Export or copy local data before any reset.
Managed cloud AI, paid billing, and team administration are not active Public Alpha promises. Their UI or backend availability may depend on the current build.
Safe diagnostic bundle
For MCP-enabled diagnostics, use the public export_diagnostic_bundle tool or the current headless diagnostic command. The bundle is intended to be secret-free, but review it before sharing. It should contain versions, platform information, MCP status, recent diagnostics, and relevant log tails rather than API keys.
When MCP is not available, collect only the latest application log and the exact command-line output. Include:
- app version/build and operating system;
- the smallest reproducible sequence;
- expected and actual behavior;
- provider, model/backend, and network conditions;
- whether the issue survives a fresh copy or a reversible configuration rename.
Never paste API keys, access tokens, cookies, service-role credentials, or private PDFs into an issue.