Troubleshooting

This page covers the most common issues users encounter with Quira and their solutions. If your issue is not listed here, please check the GitHub Issues or ask on Discord.

Installation issues

macOS: "Quira can't be opened because it is from an unidentified developer"

Problem: macOS Gatekeeper blocks Quira because the alpha builds are not yet signed with an Apple Developer certificate.

Solution:

1. Right-click (or Control-click) the Quira application in Finder
2. Select "Open" from the context menu
3. Click "Open" in the confirmation dialog

Alternatively, you can allow Quira in System Settings > Privacy & Security > Security.

macOS: Quira crashes on launch (Apple Silicon)

Problem: The AI model runtime requires the Accelerate framework, which may fail if Xcode Command Line Tools are not installed.

Solution:

xcode-select --install

Linux: Missing shared libraries

Problem: Quira depends on GTK4, WebKitGTK, and other system libraries that may not be installed by default.

Solution (Ubuntu/Debian):

sudo apt install libgtk-4-dev libwebkitgtk-6.0-dev libssl-dev pkg-config

Solution (Fedora):

sudo dnf install gtk4-devel webkitgtk6.0-devel openssl-devel pkg-config

Solution (Arch):

sudo pacman -S gtk4 webkitgtk-6.0 openssl pkg-config

AI model download failures

Model download hangs or fails at a percentage

Problem: The initial AI model download (approximately 2-4 GB depending on the model) may fail on slow or unstable connections.

Solution:

1. Check your internet connection stability
2. Retry the download — Quira supports resume from the last checkpoint
3. If the download repeatedly fails, download the model manually:

   # Download the model file directly
   curl -L -o ~/.quira/models/phi-3-mini-4k.gguf \
     https://models.quira.dev/phi-3-mini-4k-instruct-q4_k_m.gguf

Model fails to load: "Insufficient memory"

Problem: The default model (Phi-3 Mini, 4-bit quantized) requires approximately 3 GB of RAM. On systems with limited memory, the model may fail to load.

Solution:

• Close other memory-intensive applications
• Switch to a smaller model in quira://settings/ai/model
• On Apple Silicon Macs, ensure the unified memory is not heavily consumed by other apps

Context Graph not building

Pages are not appearing in the Context Graph

Problem: You are browsing but new pages are not being added to the graph.

Solution: Check these common causes:

• Incognito mode — The Context Graph is disabled in Incognito/Private windows by design. Switch to a regular window.
• Domain exclusion — The page's domain may be on the exclusion list. Check quira://settings/security/exclusions. Banking, email, and medical sites are excluded by default (see Content Filtering).
• Context Space paused — The current Context Space may be paused. Check the Space indicator in the toolbar.
• Page too transient — Pages viewed for less than 3 seconds are not added to the graph by default. This threshold can be adjusted in settings.

Context Graph queries return no results

Problem: Natural Language Queries return empty results even though you have browsing history.

Solution:

• Wait for the indexer to complete — after a restart, reindexing may take a few minutes
• Check the AI model status at quira://settings/ai — the model must be loaded for semantic search
• Try simpler queries or exact keywords first to verify the database is accessible

Performance issues

High memory usage

Problem: Quira uses more memory than expected, especially with many tabs open.

Solution:

• Reduce open tabs — Each tab consumes memory for the page and its context. Use Context Spaces to organize and close inactive tabs.
• Disable graph auto-render — The real-time graph visualization can consume significant memory. Disable it in quira://settings/graph/auto-render and open it on-demand instead.
• Use a smaller AI model — Smaller quantized models use less memory at the cost of slightly reduced accuracy.

Slow graph rendering

Problem: The Graph Visualization is slow or unresponsive with large graphs.

Solution:

• Enable WebGPU acceleration — Check that WebGPU is enabled at quira://settings/graph/renderer. Fall back to WebGL2 if your GPU does not support WebGPU.
• Reduce graph scope — Filter the graph by time range or Context Space to reduce the number of visible nodes
• Increase force-layout timeout — Large graphs may need more simulation steps. Adjust at quira://settings/graph/layout-iterations

Build from source errors

Rust compilation fails: "error[E0658]: use of unstable library feature"

Problem: Quira requires Rust nightly due to some unstable features used in the Gecko integration layer.

Solution:

rustup toolchain install nightly
rustup override set nightly

Node.js build step fails

Problem: The UI layer requires Node.js 20+ and specific npm packages.

Solution:

# Verify Node.js version (must be 20+)
node --version

# Clean and reinstall dependencies
rm -rf node_modules
npm install

# Retry the build
just build

Gecko build fails: out of disk space

Problem: Building Gecko from source requires approximately 30 GB of disk space for intermediate build artifacts.

Solution:

• Ensure at least 40 GB of free disk space before starting the build
• Use just build --release instead of debug builds to reduce artifact size
• Set CARGO_TARGET_DIR to a drive with more space if your home directory is constrained