Diagnostic Tools

Elftia has a complete set of built-in diagnostic tools to help you troubleshoot issues, collect logs, manage cache, and optimize the database. All diagnostic functions are located in Settings → System page.

Diagnostic Information Export

Export Diagnostics

Collect complete diagnostic information from Elftia runtime and package it as a shareable file.

Steps:

1. Open Settings → System.
2. In the "Diagnostics & Caches" area, click the Export Diagnostics button.
3. The system begins collecting information (button shows Collecting...).
4. After collection completes, choose a save location.

Information Included:

Content	Description
App Version	Elftia version, Electron version
Operating System	OS type, version, architecture
Runtime Environment	Node.js version, memory usage, CPU info
Provider Configuration	Configured providers list and status (no API Keys)
MCP Servers	Configured MCP servers list and connection status
App Settings	Current app configuration (sanitized)
Runtime Logs	Recent app runtime logs
Database Status	Database size, table statistics

info

Exported diagnostic information is sanitized and will not include API Keys, passwords, or other sensitive information. You can safely share diagnostic files with technical support or the community.

Export Format Options

Diagnostic information supports multiple export formats:

Format	Description	Recommended For
JSON	Single JSON file	Quick sharing, online viewing
ZIP	Complete diagnostic package	Includes log files and complete information for detailed troubleshooting

Copy Diagnostics Log

Copy diagnostic logs directly to clipboard for quick pasting into chat or issue feedback.

1. Click the Copy diagnostics log button.
2. Log contents are copied to clipboard.
3. Paste where needed.

View Diagnostic Logs

After Export Diagnostics or Copy Diagnostics Log operations, diagnostic results display in the log area below the page in green monospace font. You can directly view and review the diagnostic information on the page.

Cache Management

Clear Caches

Clear Elftia's local cache data, including model list cache, search cache, etc.

Steps:

1. Click the Clear Caches button (red danger button).
2. Wait for clearing to complete (button shows Clearing...).
3. After completion, page displays the clearing result.

Cleared Content:

• Model list cache (will be fetched again on next use)
• Web search result cache
• File search index cache
• Thumbnail cache
• API Key pool runtime cache

Content NOT Cleared:

• Chat history
• User settings
• API Keys and provider configuration
• MCP server configuration
• Theme settings

tip

If you encounter issues like model list not updating or stale cache data, clearing the cache usually resolves them. Clearing cache won't affect your data and configuration.

Prune Attachments

Clean up orphaned attachment files not associated with any messages to free up disk space.

Steps:

1. Click the Prune attachments button.
2. System scans all attachment files and identifies orphaned files not referenced by any message.
3. Safely deletes orphaned files.
4. Displays clearing results (number of deleted files and space freed).

info

This operation only cleans attachment files confirmed to be unreferenced and won't affect attachments in normal chats.

Database Maintenance

Database Size

The page displays the current SQLite database file size. As chat history grows, the database gradually increases.

VACUUM Optimization

SQLite doesn't automatically reclaim disk space after deleting data. VACUUM operation rebuilds the database file to reclaim space occupied by deleted data.

Steps:

1. In the database maintenance area, click the VACUUM button.
2. Wait for the operation to complete (button shows in-progress state).
3. After completion, displays optimization result and new database size.

Notes:

• VACUUM operation temporarily creates a database copy; ensure disk has enough space (about 2x database size).
• Avoid closing the application during the operation.
• VACUUM for large databases may take several seconds to tens of seconds.

Recommended Frequency:

• Normal use: Once per month.
• After bulk deleting chats: Recommend executing immediately.
• Unusually large database: May have deleted but unreclaimed space; VACUUM can significantly reduce size.

Resource Cleanup

Orphaned Resource Cleanup

Shows the number and total size of orphaned resource files that can be safely cleaned up, with one-click cleanup.

Steps:

1. View "Cleanable Count" and "Cleanable Size".
2. Click the Clean Resources button to execute cleanup.
3. After completion, displays results.

Environment Detection

Located in Settings → General → Environment.

Environment detection scans your system for development tool installation status:

Tool	Detection	Display Info
Node.js	node --version	Version, installation path
Git	git --version	Version, installation path
ripgrep	rg --version	Version, installation path
uv	uv --version	Version, installation path
uvx	uvx --version	Version, installation path

Each tool has a status indicator:

• Green dot (installed): Shows version and installation path.
• Red dot (not installed): If auto-install is supported, shows "Install" button.

Auto-Install

Some tools support one-click installation directly in Elftia:

1. Click the Install button next to an uninstalled tool.
2. Button changes to "Installing..." and shows installation progress.
3. Status automatically updates after installation completes.

Tools currently supporting auto-install: ripgrep, uv, uvx.

Node.js and Git need to be manually downloaded and installed from their official websites.

Developer Mode Diagnostics

Enable developer mode (keep clicking version number in Settings → About) to get additional diagnostic capabilities:

DevTools

In developer mode, you can open/close Electron DevTools in Settings → About:

• Console: View app JavaScript logs including detailed error messages and debug logs.
• Network: View all network requests including detailed LLM API call requests and responses.
• Elements: Inspect DOM structure to locate UI issues.

Using DevTools for Debugging

1. Enable developer mode.
2. Click the Open DevTools button on the About page.
3. After DevTools window opens, switch to Console tab.
4. Observe log output; error messages usually display in red.
5. For network issues, switch to Network tab and view failed requests.

tip

When reporting issues to the community or technical support, besides diagnostic export files, error logs in DevTools Console are also very valuable troubleshooting information. You can right-click logs in Console and select "Save as" to save complete logs.

Other Diagnostic Functions

Attachment Metrics

View attachment-related statistics in the System tab:

• Total number of attachments
• Disk space occupied by attachments
• Number and size of orphaned attachments

Cache Metrics

View size and hit rate of various caches:

• File search cache
• Model list cache
• Thumbnail cache
• File tree cache

Runtime Budget

View a runtime budget overview of resource usage to understand the application's resource consumption.

Database Pagination Metrics

View performance metrics for database pagination queries to diagnose database-related performance issues.

Diagnostic Troubleshooting Flow

When encountering issues, it's recommended to troubleshoot in this order:

1. Collect Information: Click Export Diagnostics to export diagnostic information.
2. Review Logs: Search for error messages in diagnostic logs.
3. Check Environment: Confirm installation status of environment tools.
4. Clear Cache: Execute Clear Caches to remove potentially stale cache.
5. Optimize Database: Execute VACUUM to optimize database.
6. Restart App: Restart Elftia to test if issue is resolved.
7. Enable DevTools: If above steps don't resolve it, enable developer mode to use DevTools for in-depth debugging.

---

If diagnostic tools reveal specific error messages, see Common Issues or Connection Errors to find corresponding solutions.