SYSTEM DIAGNOSTICS

Solutions for common issues and problems

AUTOMATED SOLUTIONS

AUTOMATIC SETUP: Build environment issues are now automatically detected and resolved. Use the automated tools first before manual troubleshooting.

Standard Resolution Process

Run Environment Diagnostics

npm run diagnose

This checks your entire build environment and identifies specific issues.

Automatic Environment Setup

npm run setup

This automatically installs missing requirements for your platform.

Install Dependencies

npm install

This runs with automatic environment checking and setup.

Verify Installation

npm run dev

Test that the application starts correctly.

MANUAL FIXES (RARELY NEEDED)

Build/Installation Failures

If automatic setup fails, these manual commands may help:

Error: "No module named 'distutils'"

Python setuptools missing (automatically handled by setup script).

# Manual installation if automatic setup fails
# macOS (Homebrew Python)
/opt/homebrew/opt/python@3.13/bin/python3.13 -m pip install setuptools --break-system-packages

# macOS (System Python)
python3 -m pip install setuptools --user

# Windows
pip install setuptools

# Linux (Ubuntu/Debian)
sudo apt-get install python3-setuptools

Error: "prebuild-install warn install No prebuilt binaries found"

Build from source required (automatically handled during npm install).

# Manual rebuild if needed
npm rebuild better-sqlite3

Error: "gyp ERR! configure error"

Build tools missing (automatically detected by diagnostic tool).

# Platform-specific build tools
# macOS: xcode-select --install
# Windows: Visual Studio Build Tools
# Linux: sudo apt-get install build-essential

Application Won't Start

Check System Requirements

Ensure your system meets the minimum requirements listed in the requirements section.

Security Software

Antivirus or security software may block the application. Add Crono to your security software's whitelist.

Permissions (macOS)

Go to System Preferences > Security & Privacy and allow Crono to run.

Permissions (Linux)

Make sure the executable file has proper permissions: chmod +x Crono

Files Showing as "Missing"

Files may show as missing if:

The original file was moved or deleted
The copied file was manually deleted from the .crono directory
File permissions have changed

Solution: You can still access the database entry and description. Re-upload the file if needed.

Upload Fails

Disk Space: Ensure sufficient disk space in the .crono directory
File Permissions: Make sure you have read access to the source file
File in Use: Close the file in other applications before uploading
Network Drives: Uploading from network drives may be slower or fail

Database Corruption

If the database becomes corrupted:

Close Crono completely
Navigate to the .crono directory
Backup the entire directory
Delete the crono.db file
Restart Crono (will create new database)
Import from a backup if available

AUTOMATED PLATFORM SETUP

AUTOMATIC DETECTION: Platform-specific requirements are now automatically detected and installed. Manual setup is rarely needed.

Automated Setup Process

The setup script automatically handles platform-specific requirements:

macOS: Detects and installs Xcode Command Line Tools and Python setuptools
Windows: Checks for Visual Studio Build Tools and installs Python setuptools
Linux: Installs build-essential and python3-setuptools via package manager

# Automatic platform setup
npm run setup

# Or as part of installation
npm install  # Includes automatic setup

Manual Platform Setup (If Automatic Fails)

If the automated setup cannot complete, use these platform-specific commands:

# macOS
xcode-select --install
/opt/homebrew/opt/python@3.13/bin/python3.13 -m pip install setuptools --break-system-packages

# Windows
# Install Visual Studio Build Tools with C++ workload
pip install setuptools

# Linux (Ubuntu/Debian)
sudo apt-get install build-essential python3-setuptools

# Linux (CentOS/RHEL/Fedora)
sudo dnf install gcc gcc-c++ make python3-setuptools

Verification

# Verify all requirements
npm run diagnose

# Verify specific components
python3 -c "import setuptools; print('setuptools OK')"
node --version

MAINTENANCE

Database Reset

To completely reset Crono and start fresh:

# Navigate to your home directory
cd ~

# Remove the entire .crono directory
rm -rf .crono

# Restart Crono - it will recreate everything
            

WARNING: This will permanently delete all your archived files and database. Only do this if you have backups or want to start completely fresh.

Moving Data Directory

The .crono directory can be moved, but you'll need to:

Close Crono completely
Move the entire .crono directory to new location
Create a symbolic link from the original location to the new one
Restart Crono

AUTOMATED BUILD RECOVERY

Build recovery is now automated. Follow this simplified process:

Step 1: Clean Installation

rm -rf node_modules package-lock.json
npm cache clean --force

Step 2: Run Automated Setup

npm run setup

This automatically detects and installs missing requirements for your platform.

Step 3: Install with Automatic Configuration

npm install

This includes automatic environment checking and setup.

Step 4: Verify Installation

npm run dev

SIMPLIFIED PROCESS: Manual setuptools installation and platform-specific commands are now handled automatically. Most build issues resolve with the automated setup.

PLATFORM-SPECIFIC RUNTIME ISSUES

Windows Issues

Windows Defender: May flag the application as unknown software
Build Failures: Install Visual Studio Build Tools with C++ workload
File Path Length: Very long file paths may cause issues
UAC Permissions: Run as administrator if file access issues occur
Python Issues: Ensure Python is in PATH and setuptools is installed

macOS Issues

Gatekeeper: Application may be blocked on first run
Build Failures: Install Xcode Command Line Tools and setuptools
Homebrew Python: Most common cause of distutils errors
Quarantine: Downloaded files may need quarantine attribute removal
File Permissions: Check app has full disk access if needed

Linux Issues

AppImage: Ensure AppImage has execute permissions
Build Failures: Install build-essential and python3-setuptools
Desktop Integration: May need manual desktop file creation
Font Rendering: Install appropriate fonts if terminal fonts appear incorrect
Permission Issues: Ensure user has write access to home directory

PERFORMANCE ISSUES

Slow Performance

Storage Speed

Move .crono directory to SSD storage for better performance with large archives.

Memory Usage

Increase available RAM if working with very large files or many simultaneous operations.

Database Size

Large databases may benefit from periodic export/import cycles to optimize performance.

Search Speed

Use specific category filters to narrow search scope and improve response times.

AUTOMATED DIAGNOSTICS

Use the built-in diagnostic tools to check your environment:

# Comprehensive environment check
npm run diagnose

# Automatic setup and configuration
npm run setup

# Manual verification (rarely needed)
node --version
python3 -c "import setuptools; print('setuptools OK')"

AUTOMATED ANALYSIS: The diagnostic tool provides detailed analysis and specific fix commands for your platform. Manual checking is rarely necessary.

GETTING HELP

Automated Issue Resolution

Before reporting build issues, run the automated tools:

✅ Run npm run diagnose for comprehensive analysis
✅ Run npm run setup for automatic configuration
✅ Try npm install with automatic environment setup
✅ Check the output of automated tools for specific guidance
✅ Only attempt manual fixes if automated tools fail

Log Files

Crono logs important information to the console. If you're experiencing issues:

Start Crono from the command line to see console output
Look for error messages or warnings
Include these logs when reporting issues
For build errors, include the complete npm install output

System Information

When reporting issues, include:

Operating system and version
Output of npm run diagnose (most important)
Output of npm run setup
Complete error message from npm install
Steps to reproduce the problem
Any manual fixes attempted

Safe Mode

If Crono is crashing on startup, try these troubleshooting steps:

Check if the .crono directory is accessible
Verify file permissions on the database
Try starting with a fresh database (backup first)
Check available disk space

EMERGENCY PROCEDURES

Complete System Recovery

Backup Current State

Before any recovery action, backup your current .crono directory entirely.

Reinstall Application

Download and reinstall Crono Desktop with a fresh copy.

Restore from Backup

Import your most recent export archive to restore your data.

Verify Functionality

Test all major functions: upload, search, export, and file operations.

PREVENTION TIP: Regular exports and system maintenance can prevent most serious issues. Keep backups and monitor disk space regularly.

FAQ

Why does npm install fail with "No module named 'distutils'"?

Python 3.12+ removed the distutils module. Install setuptools: python3 -m pip install setuptools (see platform-specific commands above).

Should I use Node.js 22 or an older version?

Node.js 18 or 20 (LTS versions) have better prebuilt binary support and fewer build issues. Use Node 22 only if you need its features and are willing to build from source.

How do I know if the build setup is correct?

Run the diagnostic commands above. You should see: Node.js version, Python version, "setuptools OK", and build tools version.

Can I skip the build process?

No, better-sqlite3 requires native compilation. You must have proper build tools and Python setuptools installed.

Can I recover deleted files?

Files deleted from Crono are removed from the archive but original files remain untouched. You can re-add files from their original locations.

What happens if I move the original files?

Crono will show them as "missing" but the copied versions in .crono remain accessible. You can update file paths or rely on the copies.

How do I clean up orphaned files?

Export your database, perform a fresh install, and import the archive. This will clean up any orphaned or corrupted data.

Can I use multiple Crono instances?

Each user account can run one Crono instance. For multiple archives, use export/import to switch between datasets.

AUTOMATED SOLUTIONS: Installation issues are now automatically detected and resolved by the setup scripts. Manual troubleshooting is rarely needed. Use npm run diagnose and npm run setup for comprehensive automated assistance.