Troubleshooting

This document provides guidance for diagnosing and resolving common issues encountered during the installation, development, and use of the PIXONA application. The solutions are derived directly from the project's source code and configuration. For further help, you can review console logs for detailed error messages or open an issue on GitHub.

Sources: README.md:213-222

Common Issues & Solutions

The following table outlines common problems and their recommended solutions, as documented in the project's README.md.

Sources: README.md:207-219

A general troubleshooting flow can be visualized as follows:

This diagram illustrates the initial steps to take depending on the type of problem encountered, leading to more general debugging practices.

Sources: README.md:207-222

Installation and Dependency Issues

Problems during the npm install phase often relate to environment setup or dependency conflicts.

Prerequisites

Ensure the following prerequisites are met before installation:

• Node.js: v18.x or higher
• npm: v9.x or higher

Sources: README.md:32-39

Dependency Resolution

The project uses an overrides block in package.json to enforce specific versions of transitive dependencies, which can help prevent common security or compatibility issues. If you encounter errors related to semver, minimatch, or glob, it may be due to conflicts with these overrides.

"overrides": {
  "semver": "^7.5.4",
  "minimatch": "^9.0.3",
  "minimist": "^1.2.8",
      "glob": "^11.0.0",
      "js-yaml": "^4.1.1",
      "esbuild": "0.24.0",

    "tough-cookie": "^5.0.0"
}

Sources: package.json:101-111

A clean installation is often the best solution for dependency-related build failures. This involves removing existing modules and the lock file before reinstalling.

1. del /s /q node_modules (Windows) or rm -rf node_modules (macOS/Linux)
2. del package-lock.json (Windows) or rm package-lock.json (macOS/Linux)
3. npm install

Sources: README.md:216-217

Development Environment

Issues in the development environment typically stem from the interaction between Vite, the Electron main process, and the renderer process.

npm run dev Command Flow

The dev script uses concurrently to run Vite and Electron in parallel. The wait-on command ensures that the Electron process only starts after the Vite dev server is ready on http://localhost:5173.

Script from package.json:

"dev": "concurrently \"vite\" \"wait-on http://localhost:5173 && electron .\""

Note: The README.md mentions port 8080, but the dev script in package.json uses 5173. The vite.config.ts specifies port 8080. This discrepancy might be a source of issues. The dev script should likely use the port from vite.config.ts.

Sources: package.json:6, vite.config.ts:9-12, README.md:63-65

The startup process can be visualized as follows:

This diagram shows the sequence of events for starting the development server. A failure at any step will prevent the application from launching correctly.

Port Conflicts

If the Electron window does not open, a common cause is the configured port being in use. The Vite server port is configured in vite.config.ts.

// vite.config.ts
export default defineConfig(({ mode }) => ({
  server: {
    host: "::",
    port: 8080,
  },
  // ...
}));

If port 8080 is occupied, you can change it here to resolve the conflict.

Sources: vite.config.ts:8-11, README.md:213-214

Single Instance Lock

The application enforces a single instance lock. If you try to run a second instance of the application, it will quit immediately and focus the existing window instead. This is expected behavior and not an error.

// electron/main.ts
const gotTheLock = app.requestSingleInstanceLock();

if (!gotTheLock) {
  app.quit();
} else {
  app.on('second-instance', () => {
    if (mainWindow) {
      if (mainWindow.isMinimized()) mainWindow.restore();
      mainWindow.focus();
    }
  });
  // ...
}

Sources: electron/main.ts:59-70

Application and Feature Issues

These problems occur while the application is running.

Photo Scanning and File Access

If photos do not appear after an import or scan, it could be due to file permissions or unsupported formats. The application uses IPC handlers in electron/main.ts to interact with the file system.

The scanning logic in scan-directory explicitly skips certain system and hidden folders. If your photos are in these folders, they will not be found.

• Folders starting with .
• node_modules
• $RECYCLE.BIN
• System Volume Information
• Windows
• Program Files
• Program Files (x86)
• ProgramData

Sources: electron/main.ts:153-162

The file selection dialog in the SettingsPage provides user feedback using toasts if an error occurs. Checking the application's UI for these notifications can provide clues.

// src/pages/SettingsPage.tsx
const handleBrowseFolder = async () => {
  try {
    if (window.electron) {
      const result = await window.electron.selectFolder();
      if (result.success && result.folders && result.folders.length > 0) {
        // ... success
      } else if (result.error) {
        toast.error(result.error); // Error is displayed to the user
      }
    } else {
      toast.error("File picker not available in web mode");
    }
  } catch (error) {
    toast.error("Failed to select folder");
    console.error(error);
  }
};

Sources: src/pages/SettingsPage.tsx:45-62

Duplicate Detection Failures

The duplicate detection feature relies on perceptual hashing and database queries. If it fails, it could be due to issues reading photo data or problems with the underlying database operations. The UI provides feedback via toasts.

// src/pages/Duplicates.tsx
const scanForDuplicates = async () => {
  // ...
  try {
    // ... logic to find duplicates
  } catch (error) {
    console.error('Duplicate scan failed:', error);
    toast.error("Failed to scan for duplicates");
    soundManager.play('error');
  } finally {
    setScanning(false);
  }
};

If a scan fails, the console.error log will contain specific details about the failure.

Sources: src/pages/Duplicates.tsx:49-80

Build and Packaging

Build issues are configured in electron-builder.json. If npm run build fails, ensure all files specified in the files array exist and are accessible.

"files": [
  "dist/**/*",
  "dist-electron/**/*",
  "public/**/*",
  "package.json"
],

The build process packages the output from the dist (Vite build) and dist-electron (Electron main/preload build) directories. A failure in the preceding tsc && vite build step will cause the final packaging to fail.

Sources: electron-builder.json:11-16, package.json:7