Troubleshooting

Troubleshooting & Error Guides

This page contains guides for troubleshooting common issues and using diagnostic tools.

Table of Contents

• 🚀 Jump to Rem by ID - User Guide
• 🛠 Pre-compute Card Priorities - Error Guide
• 🧹 Rogue CardPriority Tags Sanitization
• 📄 PDF Highlight Repair Tool

---

🚀 Jump to Rem by ID - User Guide

📖 Overview

The "Jump to Rem by ID" feature allows you to quickly navigate to any rem in your knowledge base using its RemId. This is especially useful when investigating errors from the pre-computation process or debugging issues with specific rems.

⚡ Quick Start

Using the Plugin Command (Recommended)

1. Press Ctrl+/ (or Cmd+/ on Mac)
2. Type: Jump to Rem by ID
3. Enter the RemId in the popup dialog
4. Press Enter or click "Jump to Rem"
5. Done! The rem opens automatically

Example:

Ctrl+P → "Jump to Rem" → tfhQYD3Q2wDw4VWUH → Enter → ✅

🎯 Common Use Cases

1. Investigating Pre-computation Errors

When you run "Pre-compute Card Priorities" and see errors:

Step 1: Check the console for error details

Error 15/268:
  RemId: tfhQYD3Q2wDw4VWUH  ← Copy this
  Reason: Processing exception

Step 2: Jump to the rem

• Ctrl+/ → "Jump to Rem by ID"
• Paste: tfhQYD3Q2wDw4VWUH
• Press Enter

Step 3: Investigate

• View the rem's content
• Check if it's corrupted
• Fix any issues
• Re-run pre-computation

2. Checking Multiple Failed Rems

When you have a list of failed RemIds:

=== FAILED REM IDs ===
abc123xyz
def456uvw
ghi789rst

Quick workflow:

1. Ctrl+/ → "Jump to Rem by ID"
2. Paste first RemId → Enter
3. Investigate the rem
4. Repeat for next RemId (command stays in recent commands)

Pro tip: The command stays in your command history, so just press Ctrl+P and it will be at the top of your recent commands!

3. Verifying Orphaned Cards

When you see "Rem not found" errors:

Use Jump to Rem to confirm:

• If popup shows "Rem not found" → The rem was deleted (orphaned)
• If rem opens → The rem exists (error was temporary)

🎨 The Popup Dialog

When you run the command, a popup appears with:

┌─────────────────────────────────────┐
│  Jump to Rem by ID                  │
│                                     │
│  Enter RemId:                       │
│  ┌─────────────────────────────┐   │
│  │ e.g., tfhQYD3Q2wDw4VWUH    │   │
│  └─────────────────────────────┘   │
│                                     │
│          [Cancel]  [Jump to Rem]   │
│                                     │
│  💡 Tip: Find RemIds in the         │
│     pre-computation error log       │
└─────────────────────────────────────┘

Features:

• ✅ Auto-focused input - Start typing immediately
• ✅ Enter key support - Press Enter to submit
• ✅ Error messages - Clear feedback if RemId is invalid
• ✅ Cancel button - Close without action
• ✅ Dark mode - Adapts to your theme

🔍 Understanding RemIds

What is a RemId?

A RemId is a unique identifier for every rem in RemNote. It looks like this:

tfhQYD3Q2wDw4VWUH

Where to Find RemIds:

1. Pre-computation error logs (Console, F12)

   Error 15/268:
     RemId: tfhQYD3Q2wDw4VWUH
   

2. URL bar when viewing a rem

   https://www.remnote.com/document/tfhQYD3Q2wDw4VWUH
   

3. Developer tools (for debugging)

   const rem = await plugin.focus.getFocusedRem();
   console.log(rem._id); // Prints RemId

✅ Success Messages

When rem is found:

🔍 Searching for rem: tfhQYD3Q2wDw4VWUH...
✅ Found rem: "What is the capital of France?"
📍 Opening rem in RemNote...

Result:

• Popup closes automatically
• Rem opens in RemNote
• Toast notification: "✅ Found: What is the capital..."

When rem is not found:

🔍 Searching for rem: tfhQYD3Q2wDw4VWUH...
❌ Rem not found: tfhQYD3Q2wDw4VWUH
💡 Possible reasons:
   • The rem was deleted
   • The RemId is incorrect
   • The rem is from a different knowledge base

Result:

• Error message shown in popup: "Rem not found: tfhQYD3Q2wDw4VWUH"
• Popup stays open so you can try again
• Toast notification: "❌ Rem not found"

🚨 Error Messages & Solutions

Error: "RemId cannot be empty"

Cause: You clicked "Jump to Rem" without entering anything

Solution: Enter a RemId in the input field

---

Error: "Rem not found: [RemId]"

Cause: The rem with this ID doesn't exist in your knowledge base

Possible reasons:

1. The rem was deleted
2. You copied the RemId incorrectly
3. The rem is in a different knowledge base
4. Typo in the RemId

Solutions:

• Double-check you copied the full RemId
• Verify you're in the correct knowledge base
• Check if the rem was recently deleted
• Try another RemId from your error list

---

Error: "Error: [technical message]"

Cause: Unexpected error during processing

Solutions:

1. Try again (might be temporary)
2. Reload the plugin (Settings → Plugins → Toggle off/on)
3. Check console for detailed error (F12)
4. Report bug if error persists

---

🛠 Pre-compute Card Priorities - Error Guide

Understanding the Error Report

When you run the pre-computation, you'll now see an enhanced error report like this:

✅ Pre-computation complete!

• Total rems processed: 41010
• Newly tagged: 40948
• Preserved manual priorities: 62
• Errors: 268
• Error breakdown:
  - Rem not found: 245
  - Processing exceptions: 23
• Total time: 443s
• Cache build time: 142s

Check console for detailed error log.

Future startups will be much faster!

Error Types Explained

1. "Rem not found" Errors

What it means: The card references a Rem that no longer exists in your knowledge base.

Why this happens:

• The Rem was deleted but the card still exists
• Database inconsistency
• The card's parent Rem was removed

Impact:

• ❌ The card was NOT tagged with cardPriority
• ❌ No priority was assigned
• The card may not appear correctly in the queue

How to fix:

The plugin now handles this automatically! When you run "Update all inherited Card Priorities", if any "Rem not found" errors are found, it will immediately offer to clean them up:

1. A summary confirms how many orphan cards were found and across how many missing Rems.
2. The full list is shown in pages of 25 (so the dialog always fits on screen).
3. Each page asks for your confirmation before proceeding — you can cancel at any point.
4. Confirmed orphan cards are removed in parallel batches of 25 with live progress toasts.

Each candidate is double-checked with a fresh live lookup before removal, so cards belonging to Rems that were only transiently unavailable are never deleted.

Tip

If you prefer to investigate manually first, you can cancel the cleanup dialog and use the "Jump to Rem by ID" command (Ctrl+/) to inspect individual RemIds from the console log.

2. "Processing exceptions" Errors

What it means: An unexpected error occurred while processing the Rem.

Common causes:

• Permission issues
• Corrupted Rem data
• Network timeout during processing
• Bug in the code logic

Impact:

• ❌ The card was NOT tagged with cardPriority
• ❌ No priority was assigned
• The Rem needs manual investigation

How to fix:

1. Check the detailed error log in console
2. Look for the specific error message
3. Try to open the Rem manually in RemNote
4. If the Rem is accessible, you can manually set priority using Alt+P
5. Report the error details if it seems like a plugin bug

How to Investigate Errors

Step 1: Check the Console

After pre-computation, open your browser's Developer Console (F12) and look for:

=== DETAILED ERROR LOG ===
Total errors: 268

Error 1/268:
  RemId: abc123xyz
  Reason: Rem not found - may have been deleted
  
Error 2/268:
  RemId: def456uvw
  Reason: Exception during processing: Cannot read property 'text' of undefined
  Details: [error object]
  
...

Step 2: Get the List of Failed RemIds

At the end of the error log, you'll find:

=== FAILED REM IDs (for investigation) ===
abc123xyz
def456uvw
ghi789rst
...
=== END FAILED REM IDS ===

You can copy this list and:

1. Search for these Rems in RemNote
2. Check if they still exist
3. Manually assign priorities if needed

Step 3: Re-run Pre-computation

After fixing issues:

1. Run pre-computation again
2. Check if error count decreased
3. Most "Rem not found" errors should auto-resolve after card cleanup

Important Notes

Error Count vs Failed Tagging

• Error count = Rems that failed to process
• Newly tagged = Rems that were successfully tagged

When to Worry

• < 100 errors out of 10,000+ rems: Normal, likely deleted/orphaned cards
• > 1,000 errors: May indicate a systemic issue, investigate
• All errors are "exceptions": Likely a plugin bug, report it

---

🧹 Rogue CardPriority Tags Sanitization

Overview

A "rogue" CardPriority tag happens when the plugin's internal property slots (like History, Created, Priority Source, Last Updated) or other structural rems accidentally receive a CardPriority powerup. This does not affect user flashcards but can inflate the "rems processed" counts and clutter the knowledge base.

The plugin provides a robust, two-tier sanitization system to find and remove these tags safely, without destroying legitimate flashcard metadata.

How to run the Sanitizer

For the Entire Knowledge Base (Batch)

Use the global command to scan your entire knowledge base and safely remove rogue tags in bulk:

1. Press Ctrl+/ (or Cmd+/ on Mac)
2. Type: Sanitize Rogue CardPriority Tags
3. Press Enter

For a Specific Rem (Debug Widget)

If you are investigating a specific rem and want to inspect and sanitize its properties directly:

1. Navigate to the rem in the editor.
2. Type /debug to open the Debug Widget below the rem.
3. The widget will list all children and properties. If it detects any rogue tags on properties, a Sanitize button will appear in the widget.
4. Click the Sanitize button to instantly clean up just that specific rem and its properties.

The Two-Tier System

Tier 1: Guaranteed Rogue Properties

These are tags tied directly to the plugin's own defined slots. The system safely identifies these by checking RemNote's internal slot definition IDs.

• Action: You will be prompted with a batch confirmation dialog showing exactly which slots were found. Upon your confirmation, they are safely removed in chunks.

Tier 2: Suspicious Properties

These are property nodes from other plugins or external sources that have the CardPriority tag but 0 flashcards. Since some third-party plugins (like custom dictionaries) legitimately use property nodes to generate flashcards, these cannot be automatically deleted.

• Action: The system will prompt you to review these "suspicious" properties one by one. You can manually inspect each rem and decide whether the tag should be kept or removed.

Safety Guarantees

• The sanitizer never touches legitimate flashcards (it specifically checks that getCards() returns 0 before flagging a rem).
• Structural rems (like folders or documents used for inheritance) are preserved.
• The process is entirely read-only during the detection phase, preventing accidental creation of missing property slots.

---

📄 PDF Highlight Repair Tool

Overview

In some cases, clicking a PDF highlight pin in RemNote does not scroll the PDF to the correct page — it either does nothing or jumps to the wrong location. This section explains why that happens and how to use the plugin's built-in Debug PDF and Repair PDF tools to diagnose and fix it.

What Causes Broken Highlights?

Every PDF highlight in RemNote is stored as a rem with a PDFHighlight powerup and a PdfId slot that points back to the PDF document rem. Navigation works by looking up this slot to find the PDF, then reading the highlight's position data.

The structure under a healthy PDF looks like this:

PDF Document [UploadedFile, Document]
└── Highlights [PDF Highlight Section, Automatically Sort]   ← canonical container
    └── Page 08 [PDFPageNumber]
        └── "Some highlighted text..." [PDFHighlight]
            ├── PDF           ← internal slot rem (PdfId)
            └── Data          ← internal slot rem (position JSON)

Highlights can break in two ways:

1. Wrong tree structure — Page nodes (PDFPageNumber) end up directly under the PDF root instead of under the Highlights container, or they land under a container that lacks the PDF Highlight Section tag (a tag that only RemNote's PDF engine can apply). RemNote cannot resolve the highlight → PDF path in either case.

2. Wrong PdfId slot — The PdfId slot on a PDFHighlight rem points to a stale or incorrect rem ID. This is the root cause of pin navigation failures even when the tree structure looks correct.

Both issues can be introduced by manual reorganization of a PDF rem, restoring from a backup, or merging knowledge bases.

Diagnosing with "Debug PDF"

1. Open the rem you want to inspect in the RemNote editor (the PDF document rem itself, or any rem that has the PDF as a source).
2. Type /debug in the editor to open the Debug Widget below the rem.
3. Scroll to the PDF Structure Debug section at the bottom of the widget.
4. Click Debug PDF.

This scans every descendant of the PDF rem and prints a full annotated tree to the browser console (F12 → Console tab). For each PDFHighlight rem, it shows:

• Its PdfId value — should match the PDF document rem's ID.
• Its Data slot (abbreviated) — contains the page number and position.
• All powerups and tags — lets you spot misclassified or missing nodes.

• "Highlights" (clhAqggSSLsPnQRPv) #tags:[Automatically Sort]          ← ⚠️ missing Section tag
  • "Page 13" (R5YpgM…) [PDFPageNumber]
    • "IV) Ondas com…" (BUOFZ2K2…) [PDFHighlight] PdfId:M2WPKqmgPTsrGYPZH
• "Highlights" (O2ZLmJU…) #tags:[PDF Highlight Section, Automatically Sort]   ← ✅ canonical
  • "Page 08" (Ly1DIl…) [PDFPageNumber]
    • "Esta norma…" (D5tTlvFT…) [PDFHighlight] PdfId:M2WPKqmgPTsrGYPZH

Repairing with "Repair PDF"

After diagnosing, click Repair PDF. The tool runs three independent checks and lists any issues it finds before asking for confirmation:

Issue	What the tool does
Page nodes (PDFPageNumber) sitting directly under the PDF root	Moves them into the canonical Highlights container
Page nodes inside a broken Highlights container (no Section tag)	Moves them into the canonical Highlights container
PdfId slots pointing to the wrong rem	Updates each to the correct PDF rem ID
PDF root missing the Document powerup	Adds the Document powerup

Important

The Repair PDF tool can only move pages into a canonical Highlights container — one that carries the PDF Highlight Section tag, which is applied exclusively by RemNote's own PDF engine and cannot be added programmatically. If no canonical container exists yet (e.g., the PDF has never had a highlight created through the normal PDF viewer), the tool will tell you what to do.

Step-by-Step: Complete Repair Workflow

Scenario: You have a PDF with broken highlight pins.

Step 1 — Create one new highlight (if no canonical container exists)

Open the PDF in RemNote's PDF viewer and make any single highlight anywhere. This forces RemNote to create the canonical Highlights container with the correct PDF Highlight Section tag. You can delete this test highlight afterwards if you like.

Tip

Skip this step if the Debug PDF output already shows a Highlights container tagged with PDF Highlight Section, Automatically Sort. The canonical container already exists.

Step 2 — Run Repair PDF

1. Navigate to the PDF rem (or any rem that has it as a source).
2. Type /debug → open the Debug Widget.
3. Click Repair PDF.
4. Review the list of detected issues in the confirmation dialog.
5. Click OK to proceed.

The tool moves all misplaced page nodes to the canonical container and fixes any PdfId slots in a single pass. A toast reports the result, and the console log shows each move and PdfId fix for auditing.

Step 3 — Verify

Click Debug PDF again and confirm:

• All Highlights containers now have #tags:[PDF Highlight Section, Automatically Sort].
• All PDFHighlight rems show the correct PdfId (matching the PDF document rem ID).
• Clicking a highlight pin in the PDF viewer navigates to the right page.

What the Tool Does Not Do

• It does not delete the now-empty broken Highlights container (you can delete it manually).
• It cannot add the PDF Highlight Section tag programmatically — that tag is system-managed.
• It does not alter the position data stored in each highlight's Data slot.