Skip to main content

Troubleshooting

💡TL;DR

Reproduce a problem on one disposable note with the exact provider, model and task settings. Inspect the progress log and reported output path. Separate authentication, generation, parsing and file-writing failures; a successful connection test does not verify the whole workflow.

Overview​

Record the Notemd and Obsidian versions, operating system, action name, provider protocol, model and a minimal reproduction. Avoid starting another task while cancellation is still settling. Preserve existing outputs and recovery files until you understand which operation produced them.

How It Works: Diagnostics​

Connection Test​

Use Test connection in the provider settings. Some presets test a model-list endpoint first and can succeed without a chat request; others perform a small chat request. Follow it with a small real task to verify the selected model and output contract.

Progress And Developer Diagnostics​

The progress surface reports task state, errors and output destinations. API activity can help distinguish a pending request from a completed or failed attempt. Enable API error debugging only when needed. Developer provider diagnostics exercise longer requests and can consume quota; use them deliberately when a short test succeeds but a real task fails.

Diagnostic bodies can contain note text, partial model output, endpoint details or credentials. Review and redact them locally before sharing. A redacted provider-profile export still needs a metadata review.

Common Errors​

API Key Invalid or Missing​

For HTTP 401, confirm that the key belongs to the selected provider/endpoint and has no accidental whitespace. For HTTP 403, inspect account permissions, project restrictions, model entitlement and billing state. Repeated retries will not repair invalid credentials.

Network / Connection Errors​

Check endpoint host, port, protocol and the route from the Obsidian device. For Ollama or LM Studio, verify the server is running and the model is available. localhost refers to the device running Obsidian, not another computer. Use the correct provider preset; runtime fallback selection is automatic rather than a user-facing transport switch.

Rate Limit (429)​

Reduce batch concurrency, inspect the provider's request/token quotas, and account for other clients using the same key. Retry settings can recover from some transient errors but cannot guarantee that every quota-related failure will succeed.

Model Not Found​

Use Fetch models when available or enter a model/deployment known to your account. Check the API version and region. Preset defaults may be historical; their presence in settings does not prove the upstream model is still available. Azure OpenAI needs a deployment name, while an Ark deployment may require its endpoint ID.

No Links / No Concepts Generated​

Inspect the actual processed output file. Check that the note contains useful source material, the selected model returned the required format, and a nonempty concept folder is enabled. Standalone extraction defaults to title-only notes with backlinks off. Restore the built-in prompt for a controlled comparison if a custom prompt removed required markers.

Output Missing Or In An Unexpected Folder​

Read the destination reported by the task. Add-links normally creates a _processed.md sibling; translation normally creates a _<language>.md file; title-generation batches report a complete folder. A custom translation folder can fall back to the source folder if creation fails. Check destination collisions and file permissions before rerunning.

Cancelled Task Left Files​

Cancellation stops further work where supported; completed writes are retained and are not automatically undone. A remote request or write already accepted may finish. Inspect per-file results and recovery/conflict paths before deleting anything or rerunning the whole folder.

Diagram Or Native Export Failed​

Types run sequentially. One failure does not block the others; cancellation stops pending types and preserves completed files. Retry failed exports through preview or history without another model request. A generation failure still requires generating that type again. Existing v1/v2 recovery records remain readable.

Diagram HTML contains a zoomable graphic; structured-summary HTML contains text, structure and evidence. Editable HTML/SVG is a renderer name, not an in-browser editor. Use native source for editing. Presentation export, including PPTX and MP4, keeps separate settings and dependencies. Diagram manual.

How to Report Issues​

  1. Reproduce with a small synthetic note and a dedicated folder.
  2. Record exact versions, action, model, settings needed to reproduce, expected behavior and actual outcome.
  3. Attach sanitized progress/error details and the smallest artifact demonstrating the problem. Remove secrets, private content and unnecessary endpoint metadata.
  4. State whether it reproduces with a single file and default prompts.
  5. Open GitHub Issues.

A screenshot alone rarely proves a file-format or cancellation issue. Include the source/output pair or a minimal reproducible sequence when possible.

Next Steps​