Troubleshooting

Model connection fails

Enter the base URL through its version segment, such as https://api.openai.com/v1; do not append /chat/completions.
Verify the API key, model name, and model type.
Run the connection check in Model Configuration.
Ollama or LM Studio must be running and reachable from the device running NoteGen.
Check whether the provider uses inherited, direct, or custom proxy mode.
For older compatible APIs, change the token-limit parameter from max_completion_tokens to max_tokens.

Sync fails or conflicts

Confirm that the provider is connected and verify token permissions, repository/bucket, and path prefix.
Existing GitHub repositories usually need Contents read/write; repository creation also needs Administration read/write.
GitLab's REST API requires the api scope. Self-hosted Gitea requires the correct instance URL.
A conflict can be merged, replaced with remote data, or overwritten with local data. The overwrite choices can discard unsynced changes.
On a new device, choose the initial Records and Settings sync direction carefully.
Device-specific values such as workspace paths are excluded by default.

MCP server does not start

Mobile supports HTTP MCP only; stdio commands are desktop-only.
Use the runtime check for Node.js, Python, uv, npx, and related launchers.
Keep commands and arguments separate. Environment variables and headers must be valid JSON.
Test the connection, then select the server from the chat toolbar.
Do not import command-based configurations from untrusted sources.

OCR or image recognition fails

OCR requires the selected language packages and may download them on first use.
Use valid language codes, for example chi_sim,eng.
macOS and mobile builds may use native OCR; other environments may use Tesseract.
VLM recognition needs a compatible online model. Prefer OCR for clean text and VLM for complex layouts.

Recording or read-aloud has no audio

Check microphone permissions and the selected input device.
Transcription requires an STT model.
Use Auto for read-aloud; configure a TTS model when the system voice is unavailable.
For imported audio, verify the format and file integrity.

Workspace files are missing

Restart after changing the workspace so all components reload the path.
Confirm that NoteGen has read/write permission for the directory.
Unsupported files may appear as non-editable.
Switching workspaces does not move files. Switch back through history or migrate them in the system file manager.

Web Clipper cannot connect

Only desktop NoteGen receives browser clips. Keep it running and enable Web Clipper under Record Settings.
The extension uses 127.0.0.1:37421. Security software, browser policy, or another process using the port can block it.
After changing the switch, refresh the target page and restart the extension. Browser-internal and extension-store pages block the selection assistant.
If the queue reaches 100 items or 50 MiB, keep NoteGen running until the backlog is delivered.

Web search returns no results

Test third-party keys under Web Search and check quota, proxy, and regional restrictions.
Confirm that the current model has web search or tool use enabled and that Web Search is on in the conversation toolbar.
If native search is unavailable, inspect third-party provider order. If those fail, confirm Basic Search is enabled.
Website login, anti-bot controls, and network conditions affect results; verify important claims at the original source.

Canvas import, generation, or sync fails

Use NoteGen canvas JSON for lossless import. Mermaid only supports compatible nodes and connectors from flowchart/graph syntax.
AI charts require an available chat model and valid data. Edit the chart request and retry after an interruption.
For PNG/SVG export problems, reduce the canvas bounds, fit the view, and check remote images.
On sync failure, preserve local data and inspect the record/settings queue before deleting or recreating canvases.

Document import fails

Encrypted, malformed, or resource-heavy files cannot convert. Remove the password, export again, or split the document.
A scanned PDF has no text layer and needs OCR first. Check complex tables, formulas, and embedded objects manually.
Use the original Markdown/CSV Notion ZIP without rearranging its internal folders.
Confirm the workspace is writable and resolve duplicate destination names.

Self-hosted sync cannot connect

Check server /health/ready, the HTTPS certificate, and WebSocket reverse-proxy support.
Confirm client/server compatibility, correct device time, and sign in again.
Protect the recovery key. Before resetting a device or account, verify another device and server backups.
If a library maps to the wrong workspace, disable automatic sync and export a ZIP before any overwrite.

Update or launch fails

Confirm the package matches the platform and CPU, then download it again from the website or GitHub Releases.
Close every running NoteGen process before updating; security software may lock installer files.
If a new version does not launch, preserve the application-data directory and workspace. Do not clear data before collecting redacted diagnostics.
Downgrades may not understand a newer database. Prefer a ZIP created by a compatible version.

When opening an Issue, include the NoteGen version, OS version, reproduction steps, expected result, and actual result. Remove API keys, tokens, private paths, and note content from logs and screenshots.